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C CODE FOR THE PC 

source code, of course 

NE W! DRAPrep (embedded SQL to C translator, supports Oracle, Sybase, SQL Server, XDB, Novell XQL, SQLBase, and QE-Lib).$1,500 

C++ Virtual Memory Objects (btrees, lists, arrays, and other multiple memory classes in heap, EMM, and swap file; no royalties).$750 

Embedded DOS (full-features, real-time, multitasking, 3.31-compatible DOS for embedded system and self-bootable installations).$375 

Spell Time (spelling checker for incorporation into text products; no royalty; large dictionary; small and fast).$300 

C++ Imaging Objects (C+ + object library for imaging, PCX & TIFE convolutions, print with ditner, diffusion & halftones).$290 

ZIP Image Processor & Victor Image Library Version 2.0 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

Tirbo'+X (Release 3.0; HP, PS, dot drivers; CM fonts; Lal+X; MetaFont).$250 

C++ Rogue Wave tools.h++ or math.h++ Class Library (extensive docs).each $240 

C++ Meijin++ (C++ class library for modeling & simulation; queues, statistical tools, fourier transforms, differential equations; no royalties) . . $220 

NEW! PxSQL (SQL for Borland’s Paradox Engine; ANSI X3.135-1989 SQL-DML standard; network server not required).$180 

NEW! Embedded DOS Utility SDK (C source for standard DOS utilities— FDISK, FORMAT, COMMAND.COM and eight more).$170 

c.pslib (PostScript generation library for C programs; includes complete graphics, font, rotation & paragraph support.$170 

WKS Library Version 2.01 (C program interface to Lotus 1-2-3, dBase, Supercalc 4, Quatro, & Clipper) .$155 

Empty Shell (run a program in an empty DOS shell; written in assembler for speed and small size; C call interface).$150 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).each $150 

C++ Delorie GCC for MS-DOS (Version 1.05; includes C+ + , assembler, DOS extender, 387 emulation; complete source code and makefiles) . . $150 

Heap Expander (Version 3.0, virtual memoiy manager using expanded memory, extended memory and disk; XMS, VCPI, LIM).$135 

CBTree (B+tree ISAM driver, multiple variable-length keys) .$135 

TE Editor Developer’s Kit (full screen editor, undo command, multiple windows; with word processing: $195; Windows 3.0: $200).$130 

XMEM (extended and expanded memory manager; written in assembler with C call interface; swaps to disk; small and fast).$130 

Booter Toolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

WinMem (unlimited global memory handles for Windows 3.0, 4-byte overheadper block rather than 20, virtual memory for 286).$110 

CSIM (discrete event simulator library; clocks, chains, future events, multiple servers, queues, reports).$100 

PC/IP (CMU/MIT TCP/IP for PCs; Clarkson drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . $100 

Heapman (application memory management for Windows 3.0; 64K bytes of heap space; includes memory browser/debugger) .$100 

EZfrieve (Slovell Btrieve access with data dictionary and data manager; no royalties).$100 

NEW! EZBase (C interface to dBase files; create, read, wnte & update .DBF and ,DBT, includes index support).$100 

CDB for DOS & Unix (database toolkit; ISAM, DDL, relational & network, space reuse, concurrent access; fast, no royalty).$95 

Kier FinanceLib (interest, conversions, annuities, depreciation, cash flow, bonds, etc).$95 

PowerSTOR (Version 1.2; extended heap space on extended memory, expanded memory, and/or hard disk).$95 

Script Interpreter (a command script interpreter for DOS-based systems; C-like script language; lots of features).$90 

Visions 1.20 (text window user interface management system; includes mouse support and background processing).$80 

VMEM (virtual memoty manager by Blake McBride, Version 3.6, LRU pager, dynamic swap file, image save/restore).$80 

cbase (C database library, sequential & b+-tree random access, buffered block I/O, file-level locking).$75 

TheeDraw (PostScript display of labeled hierarchical trees; DOS & Windows screen display included; Moen algorithm).$75 

C++ FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C++).each $65 

Foundations-1 C++ Class Library (ASCII record I/O, bit arrays, exception handling, B-tree, persistent objects).$60 

C++ LDB (Loose Data Binder, persistent data objects for C++; handles pointers between objects) .$60 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

MEM.WING (global memoty manager for Windows, supports standard C memory allocation calls to "wing” your old C code into Windows) . $55 

FinanC (large collection of financial function including bond, inventory, stock portfolio, & cash flow).$55 

Mini IDL (interface generator for complex data; single inheritance, translator & table generator tools, ASCII external form only)).$50 

CALC (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

Floppy TAR (TAR backup and restore on MS-DOS devices; direct access to non-standard devices) .$50 

SuperGrep (exceptionally fast, revolutionaiy text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obi files to .asm files; output is MASM compatible) .$50 

CLIPS Version 5.0 (rule-based expert system generator; advanced manuals available at additional cost).$50 

C+ + NIH Class Library & Book (basic C+ + classes & Data Abstraction and Object-Oriented Programming In C+ + in softback by Keith Gorlen) $50 

Editor Pack (15 public domain editors; including microEmacs 3.11, Stevie, Elvis, Moke, mg2a, DTE, Jove, & Origami).$50 

NE W! MicroC C Compiler (retargetable C compiler with optimizer, libraries, and utilities; lots of docs, very portable, tables for 5 cpu’s).$45 

NEW! TOUR (beautiful traveling salesman problem solver, finds minimum length paths quickly, includes graphics & plotting programs) .$40 

Cint (C interpreter).$40 

DES Encryption & Decryption (2500 bits/second on 4.77 MHz PC for on-the-fly encryption at 2400 baud; domestic distribution only) .... $40 

RXC & EGREP Version 2.0 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

Bison & BYACC(YACC workalike parser generators; documentation; no restrictions on use of BYACC output).$35 

C++ Object-Oriented Programming in C+ + (code from the book by Naba Barkakati).$30 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

REGX Plus (Version 2.0, search and replace string manipulation routines based on regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

UUPC Pack (UUCP for the PQ UUPC Version 1.11Q by Wonderworks and smail/PC Version 2.5 by Stephen C. Trier).$25 

PERL for MS-DOS (C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

Updated! Tfcl Version 6.1 (Tbol Command Language; add shell programming capability to any command line; elegant command line language) .... $25 

FLEX (fast lexical analyzer generator; new, improved LEX; BSD Version 2.3.6 with docs).$25 

Livermore Loops in C (the famous Fortran benchmark transliterated to Q includes technical report as PostScript file) .$20 

XLISP 2.1 (includes Almy improvements).$20 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better; keeps track of software development).$20 

C++ Gperf Version 2.5 (GNU’s perfect hash table generator; requires DJ gcc; includes executable; specify Cor C++) .each $20 

SDBM (fast, disk-based hash table manager for really large hash tables; clone of Unix ndbm) .$20 

NEW! PCAL Personal Calendar (generates PostScript calendar for any month or year, lots of options, personalization file for your dates & schedule) $20 

Unix/386 

X-Windows (client & server, shared library, Xlib, executables, XAW etc.; code is dills on X11R4; TCP or same machine).$200 

Kyoto Common Lisp (Austin flavor, naturally; Version 1.530; includes GCC and Portable Common Loops (PCL)).$140 

GNU Emacs Version 18.55 (includes complete source & executables).$125 

Waffle BBS (interface to UUCP & B or C news; internal forums; files section; external processing; full USENET support).$120 

GNU C Compiler (gcc) Version 1.39 (includes complete source & executables).$100 

ViewComp Spreadsheet (internal termcap; printer output; hardcopy docs).$80 

GNU Debugger (gdb) Version 3.5 (includes complete source & executables).$60 

Gillespie Pascal-to-C?many flavors of Pascal handled; readable & maintainable output).$25 

Gosling Spreadsheet Pack (variants of the 1982 Gosling spreadsheet including PubhCalc and SC version 6.10; 1 MS-DOS variant) .$25 

NEW! PDKSH (Public Domain Korn Shell).$20 


11100 Leafwood Lane much more ... ask for catalog FAX: (512) 258-1342 
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Feature Summary 
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About Control Palette 


Control Palette Information 
(C)Copyright 1991 Blaise Computing Inc. 
Version 1.00 



There’s A New Meaning To 
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...with the Windows Control Palette™ for C, C++, Turbo Pascal and Visual Basic. 
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trols that make your application look and 
operate like just another interface? With 
Windows Control Palette™ you can 
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(DLL), Windows Control Palette is a set 
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dialog boxes, the Windows Control 
Palette gives you options that the masters 
could only dream about. 

Everything is under Control... 

The Windows Control Palette reference 
manual describes in detail how to use the 
custom controls and how to modify them. 
A DLL of bitmaps makes it easy to cus¬ 
tomize the controls to your preference. 
Examples are provided for C, C++, Turbo 
Pascal, Visual Basic, Smalltalk/V and 
Actor 4.0. All source code is included! 



BLAISE COMPUTING INC. 


For applications suitable for framing... 

Windows Control Palette requires Win¬ 
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Call our order department toll free at 
(800)333-8087! 
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From 

the Editor 


Since this month's theme is debugging, I think it's worthwhile to debunk some 
Windows myths that programmers still waste time rediscovering. You can find these 
myths perpetuated in Windows programming books and even some magazines (not 
ours, I hope!). 

Myth #1: Avoid locking memory. A real-mode myth. Most developers gave up 
on real mode when Windows 3.0 came out. Microsoft gave up on it in Windows 3.1. 
So go ahead, ignore that huge Petzold chapter on movable memory, leave that 
memory locked, and take advantage of a concept from the 1960s that finally made 
it to the PC: virtual memory. 

Myth #2: Do not use the large memory model. The real restriction is: make 
sure all your static data resides in the default data segment, with the local heap and 
the stack. Although that was a difficult restriction if you were writing large-model 
code with a Microsoft C compiler, other vendors (like Borland and Zortech) made it 
fairly easy to direct all the static data to the default data segment. In fact, if you 
want to write large (>64Kb worth of C++ objects) C++ programs with any degree of 
portability, large-model programs are your only option, due to the implicit this 
pointer. 

Myth #3: Use the WEP for any necessary DLL cleanup. Ouch! The reality is: do 
absolutely nothing in your WEP but return zero and keep your fingers crossed. How 
many Windows 3.0 programs out there are crashing or waiting to crash because we 
believed the SDK documentation? Windows 3.1 is supposed to fix this. 

Myth #4: Hook functions must be in fixed DLLs. Another real-mode myth. Put¬ 
ting code in fixed DLLs kept it from being swapped to expanded memory in real 
mode. Since real mode is a thing of the past, your DLL does not have to be fixed in 
memory. In fact, the real restriction is that SS will not equal DS when your hook 
function is called. If you observe that restriction, you can put the hook function right 
in your application and avoid using a DLL altogether. 

After my initial experience writing Windows code, I came to the conclusion that 
the much-feared Windows programming learning curve is not the learning curve of 
sophisticated concepts, but the learning curve of inferior documentation, both at the 
design level and the function level. That's how programming myths get started. 
Although that is bad news for programmers, it gives Windows/DOS Developer's Jour¬ 
nal a lot to write about. By presenting the hard-earned experience of programmers 
in the trenches, we can save you some precious development time and earn our 
place on your desk. Drop us a letter and debunk your own favorite Windows or DOS 
programming myth. 

Ron Burk 


Editor 

CIS: 70302,2566 
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After programming your initial test, 
Microsoft Tkstcan save you hours, even days, 
with each subsequent test. 



Use a recorder to auickly create 
test scripts that simulate keystrokes and mouse 
movements in your application. 


Test your apps. 
Not your patience. 

Testing your Windows™ based applications can be painfully 
slow. Then again, not testing them can be disastrous. 

But finally you can do it fast and do it right. With Microsoft' 
Test for Windows Software Testing Automation Tool. 

Once you’ve prepared your test scripts, Microsoft Test 
runs automatically. Without goofing up. 

It simulates keystrokes and mouse movements, 24 hours 
a day. And it constantly evaluates your application, while record¬ 
ing what went wrong and what went right, and why. 

What’s more, it can finish a test in days, instead of weeks. 
Plus, it repeats each test exactly, for greater accuracy. 

The final result: you can run higher quality tests. You can 
produce higher quality applications. And you can save literally 
hundreds of hours in the process. 

So call us at (800) 541-1261, Department A06. 

We’ll show you how to put your Windows-based applica¬ 
tions through their paces. At a much faster pace. 

© 1992 Microsoft Corporation. All rights reserved. Printed in the USA. For more information inside the 50 United States, call (800) 541-1261, Dept. A06; 
outside the U.S. and Canada, call (206) 936-8661. Customers in Canada, call (800)563-9048. Microsoft is a registered trademark and Windows and Visual 
Basic are trademarks of Microsoft Corporation. 


PROGRAMMER'S TIP 


Key Features 

• TestDriver, the environment for developing 
and running test scripts, includes an enhanced 
version of the Basic language, TestBasic, for 
efficient script creation. 

• Functions which simulate keystrokes and 
mouse movements reduce testing time. 

• Trap command, to trap unexpected events, 
such as UAEs, allows test script to stay in 
control. 

• Recorder for keystrokes and mouse movements 
creates editable TestBasic test scripts easily. 

• High-level English-like functions help users 


create test scripts quickly. 

Fast, exact comparisons between actual and 
expected results verify application quality. 
Screen capture and compare functions provide 
additional test results to verify application 
functionality. 

No hooks or debugging code needed, so 
Microsoft Test can be used with the final 
version of almost any application for Windows, 
no matter what development tool was used to 
create the application. 


As an alternative to using Basic 
script language, call the Microsoft 
Test API with your favorite lan¬ 
guage, such as Microsoft Visual 
Basic" or Microsoft C. Included in 
the product are.Hand. LIB files 
for linking the TestCtrl, TestDlgs, 
TestScrn and TestEvnt functions 
into your C program. 

Microsoft 
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Writing a 


A windows debugger is a relatively complex beast com¬ 
pared to a DOS debugger. While portions of a debugger (such 
as statement-stepping algorithms and high-level symbol table 
manipulation) can be the same in DOS and Windows, the 
code that interacts with the underlying operating system will 
necessarily be very different. Consider, for example, the 
similarity of Borland’s TD and TDW, or Microsoft’s CV and 
CVW: in both cases, the user interface code, as well as the 
format of the symbolic debugging information, is nearly iden¬ 
tical between the DOS version and the Windows version. On 
the other hand, almost none of the code that loads a pro¬ 
gram, reads memory from the debuggee process, or causes 
the debuggee to single-step or run is reusable. The nature of 
the two operating systems is that different, even though Win¬ 
dows theoretically runs as an extension of DOS. 

What are some of the challenges of writing a Windows 
debugger and how does it differ from a DOS debugger? In this 
article, I will first present some of the major issues involved in 
writing a Windows debugger and then discuss how to deal 
with those issues. In many cases, I will refer to functionality 
in Microsoft's toolhelp.dll. toolhelp.dll became available 
with Windows 3.1, but is backward compatible with Windows 
3.0. Thus, you can apply the techniques described here to 
both Windows 3.0 and 3.1 (with two exceptions described 
later). (For a more detailed look at toolhelp.dll, see the 
forthcoming Undocumented Windows [Addison-Wesley, June, 
1992], of which I am a co-author.) Also, toolhelp.dll and the 
techniques I describe here are specific to protected-mode 
Windows. Real-mode Windows debugging is a different can of 
worms, and is covered in chapter 7 of Undocumented DOS. 

Challenges 

The first critical thing that any debugger must be able to 
do is load the program to be debugged. Under DOS, you can 
load the debuggee by using a variation of INT 21h, function 
4Bh. This variation was undocumented when it first appeared 




Matt Pietrek is a developer at a large California tools vendor. He special¬ 
izes in debuggers, and file browsing/conversion utilities. He is a co-author 
of the upcoming book Undocumented Windows. Matthew lives with his 
wife, April, and their two dachshunds, Theodore and Gunther, near the 
beach. 
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in Undocumented DOS, but is now documented in the DOS 5 
Programmers’s Reference. Unfortunately, the latter document 
contains little information on how to use this feature and 
even has a bug: the last two elements of the LOAD structure 
are interchanged. 

If you execute an INT 21h function 4Bh with the AL set to 
Olh, DOS loads the process into memory, but does not jump 
to its entry point. Windows does not supply a similar function; 
calling WinExecf) or LoadModulef) starts up the new task 
with no way for the debugger to control the task's execution. 

The flip side to this issue is how to terminate the debug- 
gee process. Under DOS, the basic idea is to simply switch 
what DOS considers to be the current process by setting the 
current PSP, and then invoke the standard DOS exit call (INT 
21h, function 4Ch). This trick does not work for a Windows 
application, so a different approach is required. 

Assuming you can load the debuggee, how do you make it 
execute? Once again, under DOS, you first need to make sure 
that you are in the proper “context.” If you are executing 
debugger code, then the current PSP should be the 
debugger’s. When the debuggee needs to execute, you must 
switch the current PSP to the debugee's PSP. A DOS debugger 
can assume that either the debugger or the debuggee is run¬ 
ning. However, since windows is a multitasking system, a 
Windows debugger has to be selective about which interrupts 
it processes, which program terminations it acts on, and so 
forth. 

A debugger needs to be able to read and write memory in 
order to insert and remove breakpoints and disassemble in¬ 
structions. Protected-mode Windows presents two problems 
in this area. The minor issue is that you cannot simply use a 
code segment selector to write to a code segment. The more 
interesting problem is that Windows has a habit of discarding 
code segments when it needs to free up memory. When the 
segment goes away, Windows makes no attempt to remem¬ 
ber that anything was written to it. When the code segment 
is accessed again (because someone called a function in that 
code segment), Windows reloads the segment from the disk 
image, and the breakpoint is nowhere in sight. 

Another complication that a Windows debugger faces is 
the problem of converting logical to physical address. Under 
both DOS and Windows, the debugger cannot determine the 
addresses of the code and data until after the operating sys¬ 
tem loads the debuggee. For that reason, symbolic debug in¬ 
formation is stored in "logical” form. Under DOS, the segment 
portion of a logical address is simply the number of para¬ 
graphs from the load address of the debuggee’s code or data, 
typically PSP+lOh. The offset portion of a DOS logical address is 
the same as in the physical address. So, for instance, if func¬ 


tion foo() is at logical address 001 A:9ABC and the debuggee's 
PSP is lOOOh, then the corresponding physical address of foo() 
will be 102A-.9ABC. (The first byte of the program is at para¬ 
graph lOlOh, and foo() is lAh paragraphs plus 9ABCh bytes 
past that.) 

Under Windows, this straightforward "address mapping" 
breaks down. A Windows program can have multiple seg¬ 
ments, and as Windows loads each segment, it assigns it a 
selector that has no relationship to the selectors for any of 
the other segments. To compound the problem, Windows 
programs can use DLLs that have their own entirely separate 
symbol table, along with multiple segments. This is quite a 
mess to contend with. 

Last, but certainly not least, comes the “mother of all 
problems.” Making the debugger itself a GUI application opens 
up a rather large can of worms. As you will soon see, there 
are very good reasons why TDW and CVW are not GUI debug¬ 
gers (although they really are Windows programs). 

The Windows messaging system is synchronous-, the Win¬ 
dows message manager will not allow any tasks to retrieve 
messages until the current message has been dealt with. 
“Dealt with” in this case means that the application has 
notified Windows that it has finished processing the message 
and is ready for the next one, typically by calling Get- 
Messagef), PeekMessagef), or Yield(). Windows relies on all 
the applications "behaving” by giving up control when they 
finish processing their messages. 

Why is this a problem? Typically, the majority of an 
application’s code is invoked as a result of receiving a mes¬ 
sage. Suppose a debugger user sets a breakpoint somewhere 
in the message processing code. When the debuggee hits that 
breakpoint, the debuggee stops in the middle of its message 
processing. As a result, the Windows messaging system is 
never told that the message has been dealt with. Thus, no 
other application in the system can retrieve its messages, in¬ 
cluding a GUI debugger. The system is deadlocked. 

TDW and CVW avoid this deadlock situation by not using 
Windows for their display. Instead, they use text mode, and 
write directly to the video memory using the predefined Win¬ 
dows selectors_ BOOOh and _ B800h. As a side note, OS/2 

Presentation Manager suffers from the same fate. Even though 
OS/2 itself is preemptive, Presentation Manager is still based 
on the “one message at a time” model. If you were to dead¬ 
lock in the above scenario under OS/2, all message processing- 
threads would be suspended, but other non-PM threads 
would continue to run. 
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Solutions 

The high-powered Windows debuggers currently available 
(TDW, CVW, and Multiscope) all use a DLL from Microsoft called 
windebug.dll (QuickC for Windows uses a modified version of 
windebug.dll). windebug.dll provides a layer on top of some 
low-level undocumented Windows functionality. A win¬ 
debug.dll user issues high-level commands such as “Load a 
process," “Step the process," or “Convert this logical address to 
a physical address.” In short, windebug. dl l does a lot of the 
hard work for you. The WINDEBUG API is a derivative of the 
OS/2 function DosPtrace(), which itself is a descendant of the 
ptrace() function from UNIX. The WINDEBUG API consists of 
one function; you pass it a pointer to a structure containing 
input and output data. When calling the function, the struc¬ 
ture contains commands such as “Read memory" and 
parameter values such as a memory address to read from. 
Upon return from the function, the structure may contain 
return information, or an indication that some event has oc¬ 
curred in the debuggee. 

Unfortunately, Microsoft abandoned windebug.dll. The in¬ 
terface to windebug.dll was never formally documented. On 
top of that, in their “Open Tools" strategy, Microsoft stated 
that WINDEBUG is out, and TOOLHELP is in. The vendors of 
Windows tools have been strongly encouraged to move 
towards the TOOLHELP API but, to date, have been slow to do 
so. TOOLHELP documention is available in the Windows 3.1 
SDK. All of the APIs and constants can be found in toolhelp.h 
or toolhelp.inc. 

TOOLHELP is a thin layer on top of the same undocu¬ 
mented functionality that WINDEBUG uses. While it is possible 
to accomplish the same things with TOOLHELP, it is up to the 
developer to provide the extra code that fills the gap between 
what a Windows debugger needs and what TOOLHELP 
provides. 


The extra functionality that WINDEBUG provides over TOOL- 
HELP is mainly in two areas: interrupt handling and notification 
handling. WINDEBUG shields the debugger from having to 
know about interrupts by taking responsibility for installing 
the appropriate interrupt handlers (INT 1, INT 3, exception 
13, and so on). As interrupts occur, WINDEBUG packages them 
up and treats them as just another event in the execution of 
the program. TOOLHELP can also install interrupt handlers for 
you, but it notifies you about them via a callback function. It 
is up to you to write the code for such things as obtaining the 
register values, determining what the current task is, and 
switching to the debugger's task. 

The other significant issue that WINDEBUG shields you from 
is notification handling. When “significant” events occur in 
Windows, it optionally calls a notification handler. Significant 
events include a task starting up, a DLL being loaded, a re¬ 
quest to output a debug string, a request for an input charac¬ 
ter (“Abort, Retry, Ignore"), and so on. You set up a notification 
handler by calling RegisterPtrace() (Windows 3.1 supplies 
an additional, but similar, function called ToolhelpHookO). 
Windows calls the notification handler with parameters in 
various CPU registers. For this reason, both WINDEBUG and 
TOOLHELP choose to install a notification handler in their code, 
and pass on the information to you in digested form. As with 
interrupts, the information you get from TOOLHELP is in a 
much more “raw" state than what you would see with WIN¬ 
DEBUG. 

Loading a Program 

Loading a Windows program for debugging requires a fair 
amount of trickery; you have to install both a notification 
handler and an interrupt handler. TOOLHELP provides two 
functions for these purposes, InterruptRegister() and 
NotifyRegister() , while WINDEBUG does the low-level 
equivalent automatically when you command it to load a pro¬ 
gram. 

with the handlers in place, you 
simply call LoadModulef) or WinExecf) 
to cause Windows to start loading the 
debuggee. At some point before Load- 
Module() or UinExec() returns to you, 
Windows calls your notification handler 
with a task start notification 
(NFY_STARTTASK). The parameter for this 
notification gives you the CS:IP that 
Windows will jump to after the notifica¬ 
tion callback returns. At this point, your 
notification handler can write a tem¬ 
porary breakpoint to the starting CS:IP 
of the program, and save the old data 
at the CS:IP, as well as the CS:IP itself. 

After setting a breakpoint and stor¬ 
ing all the necessary information, your 
notification callback function returns. 
Very soon thereafter, Windows jumps 
off into the debuggee's code. As soon 
as it does this, the CPU executes your 
temporary breakpoint, and control trans¬ 
fers to your interrupt callback function. In 
the interrupt callback function, you 


Windows 


Load debuggee 
into memory and notify 
NotifyRegisterQ handler. 


□ Jump to debuggee. 


Figure i 

Debugger 


• Install interrupt handler 

and Notify Reg ister() handler. 

• Call LoadModule(). 


□ (in NotifyRegister() handler) 

Receive NFY_STARTTASK notification. 
Save first byte of debuggee. 

Store supplied debuggee CS:IP. 

Store breakpoint interrupt (OxCC) there 
Return. 


□ (in interrupt handler) 

Verify it is INT 3 

and execution address == 

previously stored CS:IP. 

Put original opcode back in 
debuggee. 

Do DirectedYieldO to debugger task. 

• fin main debugger code) 

Original call to LoadModule() 
returns. 

Check return status. 


Debuggee 



• = executing in debugger's context 
□ = executing in debuggee’s context 

Loading a Windows Program for Debugging 
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should check to see if the interrupt really was an INT 3 and 
do whatever cleanup is desired (decrement the IP, remove 
the breakpoint, and so on). It is important to note that al¬ 
though this code resides in the debugger, it actually runs as 
the debuggee task; an interrupt is just a little unexpected side 
diversion. It is the single, shared address space of Windows 
that allows code in one program to execute in the context of 
the other (both Windows 3.0 and 3.1 use a single LDT for all 
processes). In newer operating systems such as OS/2 and Win¬ 
dows NT, each application has its own address space, which 
means that the code for dealing with breakpoints must be 
moved into the “trusted” kernel address space so that one 
application cannot unduly harm another. 

When everything is as it should be in the interrupt handler, 
it is then time to wake up the debugger. The trick here is a 
call to DirectedYield(), which was not documented in Win¬ 
dows 3.0, but has since been legitimized by Microsoft. 
DirectedYield() is similar to Yield(), but allows you to 
specify which task to yield to - in this case, the debugger. 
When you yield to the debugger, you leave the debuggee 
suspended inside of an interrupt handler and pick up execu¬ 
tion again in the debugger's task. Since the debugger was call¬ 
ing LoadModulef) or UinExec() when this chain of events 
began, the appropriate call finally returns, and you can check 
the return value to see if everything went okay. Figure 1 out¬ 
lines the sequence of events involved in loading a Windows 
application for debugging. 

Terminating a Program 

Terminating a program under Windows is, mercifully, much 
easier. As noted in the introduction, the basic idea is to some¬ 
how start running as the debuggee, and then “kill yourself." 
TOOLFIELP supplies the TerminateAppO function, which does 
just that. By using DirectedYieldf) and some other tricks, 
TOOLHELP causes Windows to switch to the specified task and 
then transfer control to a section of code inside of TOOLFIELP. 
That section of code calls FatalAppExit() and performs some 
extra trickery to prevent the standard UAE box. Beware of a 
bug in TOOLHELP that causes it to UAE if your code has not 
executed past the InitAppO call in the startup code. 

If you like to live dangerously, you could also just write a 

MOV AH ,4Ch 
INT 2lh 

sequence into a code segment of the debuggee. After that, 
simply resume execution at the CS-.IP of the modified code, 
and the task shuts down. At one point, a certain debugger 
was using this technique, but there is no need to now, since 
there are “approved" methods. 

Single-Stepping and Running 

Single-stepping and running the debuggee is really just a 
continuation of the process described earlier for loading a pro¬ 
gram. Once loaded, the debuggee is suspended inside an in¬ 
terrupt handler (produced by the temporary breakpoint op¬ 
code you inserted at the debuggee's starting address). To 
make the debuggee continue execution, just switch back to 
the debuggee’s task context (via DirectedYieldO) and then 
return from the interrupt handler. To make the debuggee 


single-step an instruction, your interrupt handler must make 
sure that the TRAP flag is set in the register flag word on the 
stack that will be loaded when the handler executes an IRET. 
If you wish to run instead of single-step the debuggee, make 
sure the TRAP flag is cleared in the stack image. 

I find it helpful to think of this process as analogous to a 
boomerang. When you are in the interrupt handler, you have 
the boomerang firmly in your hand and the debuggee is not 
going anywhere. To make the debuggee move again, you 
IRET from the interupt handler (throw the boomerang). When 
the debuggee gets a single-step trap, or hits a breakpoint, or 
receives a GP fault, it comes back to you (the boomerang 
returns to your hand). This process repeats itself until the 
debuggee process dies (either naturally, via a normal exit, or 
unnaturally because the debugger kills it). Figure 2 shows the 
pseudocode for single-stepping or running the debuggee. 

Memory Reading/Writing and Breakpoints 

Accessing the memory of the debuggee process under 
Windows is a bit more difficult than under DOS. The first prob¬ 
lem is writing to a code segment in protected mode (for in¬ 
stance, to store a breakpoint opcode). Because Windows 
stores code in read-only segments, just writing to the code 
segment produces a GP fault. To actually write to a code seg¬ 
ment, you need an “alias” selector to the segment. To create 
one, you could invoke the appropriate DPMI services to allo¬ 
cate a new selector. Then, you could assign it the same base 
address and length as the code segment, but with the selec¬ 
tor marked as DATA, rather than as CODE. (Or, if you trust 
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undocumented functions, you could use 
the AllocCStoDSAlias() function 
described in Undocumented Windows.) 
To read from a code segment, you can 
just use a CS: override, but it could be 
slow if you are transferring large 
amounts of data. 

Once you have a suitable selector to 
read or write with, well-written code 
would verily that the access will not ex¬ 
ceed the limit of the segment (see Ar¬ 
thur Applegate’s article, “Preventing, 
Detecting, and Fixing Windows Memory 
Bugs,” in this issue for a C function to 
verify protected-mode pointers). A re¬ 
lated issue arises if you access a "huge” 
(tiled) block of memory, and the 
read/write request crosses a segment 
boundary. In this case the request 
needs to be split into several parts. For¬ 
tunately, TOOLHELP has a set of func¬ 
tions - MemoryRead() and Memory- 
Write () - that do all the dirty work to 
handle the necessary sanity checks and 
selector tiling issues. A program simply 


passes in a “from” address, a “to” ad¬ 
dress, and a length, and TOOLHELP 
returns either "Yes, I did it,” or “No, I 
couldn't do it.” MemoryRead() and 
MemoryWrite() are even smart enough 
to use 32-bit memory moves if possible. 

It would be nice to think that, 
having set breakpoints in protected- 
mode code segments, you've done all 
that’s required, but there is more. If the 
debugger expects the breakpoints to 
stay in place (as opposed to being in¬ 
serted and removed for every step or 
run), then it has to be able to re-insert 
them at a moment’s notice, since Win¬ 
dows may discard the code segment in 
which you stored a breakpoint opcode. 

windebug.dll handles this issue by 
maintaining an internal cache of break¬ 
points you have set. When Windows 
reloads a code segment from disk, WIN- 
DEBUG checks its cache to see if any 
breakpoints need to be reset in the in¬ 
coming segment, and sets them if 
necessary. The downside is that the 


cache in WINDEBUG is limited to 256 
breakpoints - which can cause interest¬ 
ing problems with "active-mode” Win¬ 
dows profilers that use one breakpoint 
for every area to be profiled. 

A debugger not using WINDEBUG 
must deal with discardable code seg¬ 
ments in its own code. Fortunately, 
Windows can notify your handler when 
it has reloaded a code segment. Then if 
a segment load notification occurred for 
a segment that had been previously 
written to, your notification handler 
would reset any breakpoints. You could 
choose to store necessary data by 
means of a linked list of linked lists, 
with each node in the first list contain¬ 
ing a selector value and a pointer to a 
linked list of offsets. Then, when a seg¬ 
ment load occurs, you can quickly scan 
the first list to determine if the segment 
exists in the list; if it does, then iterate 
through the list of offsets for that seg¬ 
ment, setting each breakpoint in turn. 

Alternatively, you might opt for a 
brute-force solution and simply lock 
down the code pages of interest so that 
Windows cannot discard them (see 
Timothy Adams’ article, “Intercepting 
DLL Function Calls,” in this issue for 
details on this method). Although lock¬ 
ing down code pages is not a suitable 
approach for a general-purpose debug¬ 
ger, it may fit the bill for more special¬ 
ized applications. 

Address Mapping and 
Symbolic Debug Information 

A debugger has to translate logical 
addresses (either from a .map file or 
from symbol tables a compiler or linker 
embeds in the .exe, for example) into 
physical memory addresses. As I men¬ 
tioned earlier, converting logical addres¬ 
ses in the debug information to physical 
addresses in memory is a serious issue 
under Windows. Since a program can 
have multiple DLLs, each with its own 
symbol table, the definition of a logical 
address is necessarily more complicated 
than for DOS. 

In Windows, a logical address con¬ 
sists of the module identifier (a module 
handle or the module name), the order 
of the segments in the executable file, 
and the offset within the segment. For 
instance, if WinMainf) is at offset 1234h 
in the fourth segment of the executable 
file with module name MYPROG, then the 


Figure 2 


[In the main portion of the debugger] 

• Make sure that the FLAGS image on the stack is set appropriately for 
stepping or running. 

• Do a DirectedYield() to child task. 


[In the InterruptRegister handler, running as the child] 

• return from DirectedYield() call to debugger. 

• Throw away stack frame for the InterruptRegister callback, and then 
I RET back to the child’s code. 

• Child either steps or hits breakpoint, causing the interrupt handler 
to be entered again. 

• Save away useful information, such as register values, etc 

• Do a DirectedYield() to the debugger task(). 


[In the NotifyRegister handler] 

• If the child hit a breakpoint, or stepped, then you won't get here. 

• If the child ran to completion, then you will get here, with 
a NFYJKITTASK notification. 

• Use GetCurrentTask() to determine if the task that terminated was the 
task you were debugging; if so, notify the debugger. 


Pseudocode for Stepping/Running the Debuggee 
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logical address of UinMain would be: 
MYPROG 0004:1234. 

How, then, do you convert a logical 
address in the debug information to a 
physical address that you could access? 
The answer lies in the fact that the 
Windows module table maintains a 
mapping between each segment in the 
file and the selector that Windows has 
assigned to it (the details can be found 
in Undocumented Windows). If you 
know the format of the module table, 
you can retrieve the information from 
the table relatively easily. However, 
since the table is undocumented, as 
responsible programmers we should try 
to find a “legal” solution. The docu¬ 
mented TOOLHELP function Global- 
EntryModule() allows you to obtain 
the selector for a given module handle 
and logical segment. To go the other 
way, from a selector to a module hand¬ 
le and logical segment, use Global- 
EntryHandle() . A cautionary note: 
these functions cannot distinguish be¬ 
tween multiple instances of the same 
data segment. Thus, if you run more 
than one instance of a program, the 
selector obtained for the DGROUP seg¬ 
ment will always be that of the first in¬ 
stance Windows loaded. 

As an alternative, you can watch the 
segment loads and unloads as they 
come through your notification function. 
This strategy, however, will not give 
you notifications for segments that had 
been loaded before the debugger 
started up, so you will still need to use 
the preceding method at times. 
Moreover, when Windows notifies you 
of a segment load, it supplies the as¬ 
sociated module in the form of a 
module name rather than a module 
handle, which is probably how you 
want to store it. 

The GUI Debugger Problem 

Suppose the debuggee has stopped 
at a breakpoint in a message handler. A 
vital link in the cooperative chain of 
multitasking programs has suddenly 
been knocked out of action. Now is the 
moment of truth, when the debugger 
must step in and prevent the debuggee 
process from running, but somehow 
keep the windowing system alive and 
processing messages. What can be 
done? 

Hard as it may be, the debugger 
must take over the debuggers mes¬ 


sage processing. The debugger needs to 
shut down the heart of the debuggee 
(its GetMessage()/DispatchMessage() 
loop), and substitute a replacement 
heart that keeps the system messages 
flowing, (in OS/2 Presentation Manager, 
this process is further complicated be¬ 
cause there can be multiple threads, 
each with its own UinGetMsg()/Uin- 
DispatchMsgO loop). For a more 
detailed view of the problem, refer to 
“Writing Windows-Hosted Debuggers," 
by Bob Gunderson, in the Microsoft 
Open Tools documentation (only avail¬ 
able to selected vendors). 

It is not enough just to substitute 
your own GetMessage()/Dispatch- 
Messagsf) loop for that of the debug¬ 
gee. If you did that, code in the debug¬ 
gee process would still get executed, as 
the call to DispatchMessage() would 
cause Windows to call the window pro¬ 
cedure in the debuggee. To prevent 
this, you have to subclass every win¬ 
dow the debuggee owns (EnumTask- 
Uindows () is good for this) and force all 
of them to use a new window proce¬ 
dure inside your debugger. Yechhh! 

Once it subclasses all the debuggee's 
windows, your debugger has to 
respond to the window messages in¬ 
tended for the debuggee. In most cases, 
you can simply pass the messages on 
to DefUindowProc(), but what about a 
UM_PAINT>. How do you repaint the 
debuggee's windows, since they may 
have contained text or complex 
graphics or most anything? You probab¬ 
ly want to ignore a m_CL0SE message, 
but what about a UM_SYSC0MMAND1 If 
there are DDE messages flying around, 
how do you respond? All very good 
questions. Unfortunately, there are no 
correct answers. It is up to individual 
debugger writers to decide what should 
happen. This is not a scientific process, 
to say the least. 

But wait, there's more! The debug¬ 
gee may have installed hook functions 
(to intercept keyboard messages or 
window messages, for example). To 
prevent Windows from calling the 
debuggee's hook functions, the debug¬ 
ger must install a UH_DEBUG hook. Win¬ 
dows calls the MH_DEBUG hook before 
calling any “standard" hooks, giving the 
debugger the opportunity to prevent 
the debuggee’s hooks from being 
called. Unfortunately, this hook is only 
available in Windows 3.1 or greater. The 
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debuggee may also have subclassed the windows of other 
tasks, so you have to locate and subclass those windows as 
well. Due to the way subclassing is implemented, you cannot 
determine which windows the debuggee subclassed with 100 
percent accuracy. Also, keep in mind that you have to undo 
all this subclassing and intercepting every time you start the 
debuggee up again. The complexity of handling every possible 
GUI problem can be mind-boggling. The term used for this 
whole mechanism of stepping in for the debuggee process is 
“soft mode.” 

Having seen the work required for a “soft-mode” Windows 
debugger implementation, I can now tell you that there is an 
easier way to deal with this problem of shutting down the 
messaging system. Unfortunately, once again, it is available 
only in Windows 3.1, and is certainly not a free lunch. Win¬ 


dows 3.1 supports "hard mode,” in which only one task is 
allowed to run, thus circumventing the problem of coping 
with non-cooperative tasks. To go into hard mode, the 
debugger's main loop must call LockInput() (only available in 
Windows 3.1). You pass a window handle to LockInput() and 
then only that window and its children will be able to receive 
messages. When you wish to start the debuggee process up 
again, make a corresponding call to LockInput() to exit hard 
mode. Hard mode's main benefit is that it does not require 
the debugger to process messages for the debugger and en¬ 
sures that the debuggee process will see the messages in the 
exact same order as if it were not being debugged. For situa¬ 
tions where message ordering is critical (dialog boxes, DDE 
transactions, etc.), this is the only acceptable mode for a GUI 
debugger to use. 

The implications of hard mode are 
hard to describe; they become much 
more clear when you actually ex¬ 
perience them. You cannot start up 
other applications; you cannot switch to 
existing applications; double-clicking the 
desktop will not pull up the Task 
Manager: only the debugger is running. 
The desktop itself is not receiving paint 
messages, and on occasion, you can 
drag and drop the debugger window 
around the screen, and get the ap¬ 
pearance of many, exact duplicate win¬ 
dows (would the real debugger window 
please stand upl). 

Summary 

This article has addressed some of 
the more challenging aspects of Win¬ 
dows debugger development. Interest¬ 
ingly, the techniques used here repre¬ 
sent real Windows programming, 
without a device context or a system 
palette anywhere in sight. It is reassur¬ 
ing to know that even as the world 
continues to go GUI, there is still a place 
for people who like to get their hands 
dirty in the musty corners of an operat¬ 
ing system. □ 
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-lint 


5.0 presents 
C Bug # 564 



Although this looks like a comparison of two well known programming 
languages, it is really a C function with a subtle error. Can you or your 
compiler spot it? Call if you need a hint. Refer to Bug #564. 


PC-lint will catch this and many other 
C bugs. Unlike your compiler, PC-lint 
looks across all modules of your 
application for bugs and inconsistencies. 

New - Optional Strong Type Checking 
and variables possibly not initialized. 

More than 330 error messages. More 
than 105 options for complete 
customization. Suppress error messages, 
locally or globally, by symbol name, by 
message number, by filename, etc. 
Check for portability problems. Alter 
size of scalars. Adjust format of error 
messages. Automatically generate ANSI 
prototypes for your K&R functions. 


Attn: Power users with huge programs. 

PC-lint 386 uses DOS Extender 
Technology to access the full storage 
and flat model speed of your 386. Now 
fully compatible with Windows 3.0 
and DOS 5.0 

PC-lint 386 -$239 
PC-lint DOS -OS/2 -$139 

Mainframe & Mini Programmers 

FlexeLint in obfuscated source 
form, is available for Unix, OS-9, 
VAX/VMS, QNX, IBM VM/MVS, etc. 
Requires only K&R C to compile but 
supports ANSI. Call for pricing. 


3207 Hogarth Lane, Collegeville, PA 19426 

CALL TODAY (215) 584-4261 Or FAX (215) 584-4266 

30 Day Money-back Guarantee. 


PA add 6% sales tax. 


PC-lint and FlexeLint are trademarks of Gimpel Software 
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Debugging 


Preventing, Detecting, 
and Fixing 

Windows Memory Bugs 

Arthur D. Applegate 



Most programmers, particularly C programmers, spend more time tracking down 
memory bugs than any other category of programming errors. Memory bugs are 
also the principal cause of the two biggest complaints among Windows users: "Out 
of Memory” messages and UAEs. 

This article shows you how to prevent a number of common memory bugs that 
are specific to Windows programs. It also demonstrates techniques for detecting and 
fixing memory bugs that may already be lurking in your application. The discussion 
and examples assume you are writing in C or C++ for Windows, but many of the 
principles apply to other languages. 

Preventing Memory Bugs 

The best way to deal with memory bugs is to avoid creating them in the first 
place. While this may sound easier said than done, the use of certain defensive 
coding techniques can put the odds of avoiding error greatly in your favor. 

Your C or C++ compiler is one of your best allies in preventing memory bugs. It 
can keep you from wasting time with such errors as calling functions with the 
wrong number or type of parameters, or assigning data of the wrong type to 
pointers or structure fields. 


Arthur Applegate is author of 0 ptiMem for Windows, a memory management and 
debugging DLL for Windows. He received a BS in computer science from the Univer¬ 
sity of Sydney, Australia. You may contact him at Applegate Software, 4317 264th 
Ave NE, Redmond, WA 98053-8730, (206) 868-8512, or on BIX as applegate. 


June 1992 


Windows/DOS Developer's Journal — Page 13 







































































It’s completely rational 


Microsoft’ C/C++ 7.0 now in¬ 
cludes the Windows” operating sys¬ 
tem version 3.1 SDK. For only $139, 
it’s hard to believe this development 
kit is so complete. We’re talking all 
the latest technology programmers 
have told us they want. 

But you’re still skeptical. You’re 
asking yourself what is missing? 
Well, here’s an admittedly long-wind¬ 
ed list of what’s included. 

Object linking and embedding. 
Great for creating applications that 
share diverse types of data, like text 
and graphics. An application that 
supports OLE can cooperate with 
other OLE applications, even those 
from another vendor. 

Pen computing APIs. Everything 
you need to create compelling appli¬ 
cations for the next generation of 
pen computers. There are over 300 
pages of documentation that give 
you the basic elements of Windows 
for Pen Computing. 

Multimedia APIs. Our newest 
media control interface. You can in¬ 
corporate animation, audio and video 
capability using third party devices 
and drivers. (It’s the next best thing 
to virtual reality.) 

Windows Debugging Version. 
Traps the most troublesome UAEs 
and helps you create more stable, 
robust applications. Contains GDI, 
KERNEL, and USER modules. 

GUI Setup Toolkit. It will make 
hammering out a custom Windows- 
based setup program as simple as 
writing a script file. 

Microsoft Foundation Classes. 
Now you can use the same building 
blocks we’re using to build future 
versions of the Windows operating 
system. A rich set of 60 recyclable 
object classes provides logical order 
to more than 500 functions of the 
Windows API. Menus, GDI, OLE 
1.0 and advanced diagnostics sup¬ 


port are included. Tasks such as 
registering Windows’ classes, build¬ 
ing message loops, and managing 
device contexts are automatic. 

Sample code. Over 75,000 lines. 

Zoomin. A nifty tool for magni¬ 
fying portions of a screen to help 
identify paint problems and other 
screen-related issues. 

Heapwalker. Examine the glob¬ 
al heap and local heaps used by ac¬ 
tive applications and dynamic-link 
libraries in your system. 

Editors. And plenty of them. 
Dialog Editor lets you add, modify, 
and delete custom controls as you 
design and test dialog boxes on¬ 
screen. Image Editor modifies icons, 
bitmaps and cursors. Font Editor 
alters existing feces and creates 
new ones. Hotspot Editor creates 
and edits hypergraphics or bitmaps 
in one or more hotspots. 

Spy Tools. Pssst. They make 
it possible to monitor Mouse, input/ 
output from Windows, DDE and 
other messages between one or 
more Windows-based applications. 
You can also examine message 
parameter values. 

Stress. Allows you to consume 
system resources for low-resource 
stress testing. Acquirable resources 
include the global heap, user heap, 
GDI heap, disk space and file han¬ 
dles. (Less job stress for you.) 

Wdeb386. Now test and debug 
dynamic link libraries and Windows- 
based applications running in stand¬ 
ard or 386-enhanced mode. 

Multi-resolution bitmap compiler. 
Combine color and monochrome 
bitmaps with different resolutions 
into a single graphic. 

Help Compiler. Create Help sys¬ 
tems for applications that will take 
advantage of the new Windows 3.1 
Help engine. Both context-sensitive 


and topical searches of Help files. 

Compiler features. Unrestrict¬ 
ed pre-compiled headers for speedy 
throughput. Explicit or automatic 
inlining of any C/C++ code for fest¬ 
er executions. Compressed code 
for size reductions. 

CodeView’Debugger. This win¬ 
dow-oriented debugger is a power¬ 
ful, easy-to-use tool for analyzing 
MS-DOS’ or Windows-based pro¬ 
gram behavior. Test the execution 
and examine data all at the same 
time. Display any combination of 
variables-global or local-while 
you halt or trace a program’s exe¬ 
cution. Versions for dual and single 
monitor debugging, even in a win¬ 
dow, are supported. 

Source Profilers. Optimize the 
performance of all your MS-DOS- 
based or Windows-based applica¬ 
tions. Analyze your program to find 
code inefficiencies. 

Whew! If you were to get all of 
this separately, it would cost many 
hundreds of dollars. And definitely 
will in the very near future. 

On the other hand, if you use a 
Microsoft or any other C/C++ prod¬ 
uct, and order an upgrade before 
June 30,1992, it’s yours for $139. 
That includes over 5,000 pages of 
C/C++ 7.0 documentation plus the 
entire Windows 3.1 SDK online 
documentation. We’ll also throw in 
a free copy of Qualitas' 386-Max” 
for MS-DOS-based development. 

And if you want the Windows 
3.1 SDK documentation in hard 
copy (over 5,000 pages), it’s yours 
for an additional $150. 

Look. You can defy the logic of 
thinking programmers everywhere 
and pass up this historic offer. Or 
you can call your reseller. Or just 
call us at (800) 541-1261, Dept. B25. 

Microsoft 


Offer ends June30,1992. Reseller prices may vary. Offer good only in the 50 United States. ©1992Microsoft Corporation. All rights reserved. Printed in the USA. Customers inside the 50 United States, call (800)541-1261, Dept. B25.For information only: OutsuL 
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Local Heap Memory Dump 


• eliminate all unnecessary type casts 

• use C++ rather than C for type-safe memory allocation 

• use the STRICT option of 3.1 windows.h for improved com- 
pile-time type checking of Windows API calls 

• compile with stack probes on while developing 

Debug Version of Windows 

The debug version of Windows is one of the most helpful 
tools for early detection of memory bugs. Version 3.1 of the 
debug kernel finds many problems that the 3.0 debug kernel 
does not. To get the most from it, force RIPs on invalid 
parameters by including the following in your win. ini file: 


To get the most from your compiler: 


[Kernel] 

Error0ptions=l 


• use function prototypes religiously 

• set your compiler’s warning level at its highest setting 



New Dazzle/VB image control! 
Just $99 until 8/1/92! 

Display realistic 256 color images in Visual Basic! Break VB’s 
16 color barrier! Effortlessly zoom, pan and adjust colors using 
custom control properties! Dazzle/VB is the only true image 
display custom control for VB. This means that you can get 
your Windows app started without programming! But when 
you need to program for greater control, you can! And til 
8/1/92 you can save $200 off Dazzle’s list price! Also math, 
financial and comms VB products available — call: 

800-447-9120 ext. 117 

Tera Tech 3 Choke Cherry Rd # 360, Rockville MD 20850 
Int’l: (301)330-6764 Fax: (301)963-0436 BBS: (301)963-7478 
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The 3.1 debug kernel can also detect overwrites to buffers 
passed into the Windows APIs. Enable this feature by adding 
the following to your win. ini file: 

[Windows] 

ILoveBear=0 

Diagnosing Memory Overwrites 

One common bug is to allocate a memory buffer, then 
write past the end of it. This typically corrupts the header of 
the next sequential memory block, but you will not discover 
this until you call another memory allocation function, possib¬ 
ly much later. If you are allocating from a Windows local 
heap, knowing the heap's internal structure can help you pin¬ 
point the existence and source of overwrites. This information 
applies both to the heap in your default data segment and to 
heaps you suballocate in dynamic segments. The heap entry 
header format is identical in Windows 3.0 and 3.1. 

Each block allocated by LocalAlloc() is preceded by a 
header that links the entries of the heap (see Figure 1). For 
movable blocks, the header also contains the block’s handle. If 
you write past the allocated bounds of a local heap block, you 
corrupt the next block’s header. A corollary is that if a heap 
entry header is trashed, the culprit is very likely code that 
wrote into the previous block in the heap. 

Figure 2 shows a memory dump of a portion of a local 
heap. You can use HeapWalk or the dump facility of your 
favorite Windows debugger to produce such a dump. 

The dump shows two blocks in the middle of the local 
heap. The first block is an eight-byte fixed block containing 
the string "block 1”. The block’s header is at offset 0x0104, 
with the data beginning at 0x0108. Notice that the previous 
pointer in the block’s header is 0x0071 - address 0x0070 with 
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a 1 in the low-order bit indicating that the block is in use. The 
next pointer is 0x0110. 

The second block is a ten-byte movable block containing 
the string “block 2". The address of its header is, by no coin¬ 
cidence, 0x0110. The previous pointer is 0x0107 - address 
0x0104, with bits 0 and 1 set to indicate in use and movable, 
respectively. Since it is a movable block, an additional word 
just prior to the data contains the block’s handle, in this case, 
0x0076. 

If you know what you are looking at in a dump of a local 
heap, you can spot an overwrite instantly. 

Detecting Wild Pointers 

A simple, reasonably efficient way to determine whether a 
pointer is valid in protected-mode Windows is the LSL instruc¬ 
tion, which validates a selector and also tells you the size of 
the segment currently mapped to this selector. 

By using the routine shown in Listing 1 for parameter 
validation in the entry-points to your modules' APIs, you can 
eliminate a major source of intermodule memory bugs. This 
defensive strategy allows you to catch memory bugs much 
closer to the source, and hence to identify the culprit more 
quickly. 


Listing 1 

#include <windows.h> 

#include <dos.h> 

/* use /G2 option with MSC */ 
int ValidPointer(void far *Ptr) 

{ 

WORD BadSelector = FALSE; 

register WORD Selector = HIWORD(Ptr); 

register WORD Limit = 0; 


_asm 

lsl 

Limit, Selector; 

_asm 

jz 

Good; 

_asm 

Good: 

mov 

BadSelector, TRUE; 


return !BadSelector && (Limit >= LOWORD(Ptr)); 
} 

/* End of File */ 


Protected-mode Pointer Validation 


DLLs: A Memoiy Bug Minefield 

If you want to really have fun with memory bugs, write a 
Windows DLL. The challenge in writing a DLL stems from the 
fact that DLLs often reference memory they do not own and 
memory shared among all the tasks that call the DLL. 

The most obvious difficulty is that a DLL does not have its 
own stack. The stack segment belongs to the calling task, and 
is different from the DLL’s data segment. Therefore, in small or 
medium memory model programs, you cannot call standard 
runtime library functions that accept pointers. For example, 
consider the code fragment: 

char buf[40]; 

sprintf(buf, “Error: %s","SS != DS“); 

In a small data model, the generated code passes only the 
offset of buf to sprintf (), although buf is an offset into the 
task’s stack, not the DLL’s data segment. This call to 
sprintf() will therefore result in an overwrite into an ar¬ 
bitrary offset of the DLL’s data segment. 

A workaround to this problem is to use the far versions of 
the runtime library functions now available on most com¬ 
pilers. The Windows API itself provides several such functions, 
(including wsprintfO) that you can use to correct the pre¬ 
vious example: 

char buf [40]; 

wsprintf(buf, "Error: %s","near/far mismatch"); 

Yet another problem arises here. Because wsprintfO ac¬ 
cepts far pointers, parameters to the "%s" directive must also 
be far pointers. Since the prototype for wsprintfO specifies 
types only for the first two parameters, you must explicitly 
cast strings so that a segment as well as an offset will be 
pushed onto the stack. The code below does the job correctly: 


char buf [40]; 

wsprintf(buf, "Error: %s", (char far *)"no error here"); 


A simpler solution is to write large-memory-model DLLs, 
thereby ensuring that pointers are far by default. 
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Another problem with the caller 
owning the stack in DLLs is that you 
have no idea how much stack is avail¬ 
able. You should therefore be extreme¬ 
ly frugal with the stack in DLLs: 

• avoid recursive functions 

• avoid large automatic arrays 

• compile DLL entry-points with stack 

probes on 

If you use dynamic memory in DLLs, 
consider carefully whether the memory 
is associated with a particular calling 
task, or whether it is for some data 
structure internal to the DLL. Global 
memory allocated without the 
GMEM_SHARED flag is owned by the call¬ 
ing task and is deallocated as soon as 
that particular task terminates, making 
subsequent references to the memory 
from the DLL invalid. 

One solution to this problem is to 
use shared memory for all callers of the 
DLL. An alternative is to use task 
records to keep track of the specific 
tasks that the DLL serves. With the lat¬ 
ter approach you must ensure that ref¬ 


erences to memory allocated for a task 
occur only when that task calls the DLL. 

Any memory you allocate in a DLL 
with LocalAlloc() is, effectively, 
shared memory. So are any static or 
global variables in the DLL’s data seg¬ 
ment. And, of course, global dynamic 
memory you allocate with the 
GMEM_SHARED flag is also shared. 

The Infamous WEP 

A final memory problem in DLLs is 
present in Windows 3.0 but fixed in 3.1: 
that is, the Windows Exit Procedure, or 
WEP. Windows calls the WEP routine 
(sometimes!) as it is unloading the DLL 
from memory. Use the following 
guidelines for your WEP: 

• A WEP must be declared in the EX¬ 
PORTS section of your .def file. Use 
any ordinal value and the 
RESIDENTNAME keyword. 

• The WEP should be placed in a fixed 
code segment If the WEP is not placed 
in a fixed code segment and is dis¬ 
carded under low memory situations, 
the application may fail with a UAE. 


• The WEP may not contain code that 
expects data from the DLL’s data seg¬ 
ment or the calling program’s stack since 
these may already have been freed. 

• If you have more than one DLL, do 
not call between them at WEP time, 
and do not make a callback to a 
client task. The DLL you call, or which 
a client may try to call, may have 
been terminated already. 

• If a DLL is loaded with Load- 
Library (), its WEP will be called. If a 
DLL is called implicitly, Windows 3.0 
may or may not call the WEPI Your 
best bet is to do the following and 
nothing more in your WEP: 

int FAR PASCAL WEP(int x) 

{ 

(void)x; /* avoid unused 
arg warning */ 

return 1; 

} 

GlobalAlloc() /Local¬ 
Alloc () Dilemma 

It is very easy to exhaust memory 
resources in Windows without so much 
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as making a dent in available RAM. The 
most common ways to do this are to: 

• run out of selectors 

• run out of local heap space 

• run out of GDI or USER “system 

resources” 

Since Windows 3.0 and 3.1 both 
have a single LDT shared among all ap¬ 
plications, a system-wide limit of 8192 
selectors exists. Each global memory 
handle, data segment, code segment, 
resource segment, task and module in 
the system consumes one of these 
selectors. To allow for a modest 16Mb 
total Windows address space, an ap¬ 
plication can use an average of no more 
than one selector per 4Kb of memory. 
This means that you should use 
GlobalAllocf) only for large allocations 
(several Kb or more). 

LocalAl loc() works fine for small 
allocations, but is limited to 64Kb total 
heap, minus the size of your stack and 
static data. 

To avoid the possibility of exhausting 
either selectors or local heap, you really 
need to use some kind of generalized 
suballocator that can span multiple seg¬ 
ments. You can implement your own 
suballocator by using LocalAlloc() 
within GlobalAlloc ()'e6 blocks. Or you 
can use a commercial third-party 
product that manages dynamic 
memory for you. 

Frugal Memory Utilization 

In a multitasking environment such 
as Windows, it is particularly important 
to avoid hogging memory you don't 
really need. If you use GlobalAlloc() 
directly for small blocks, you waste a 
lot of memory due to the 24-byte over¬ 
head and 32-byte granularity of global 
allocations. 

if your data has dynamic extent, or if 
it is variable in size, allocate dynamical¬ 
ly rather than statically. Static space 
that is not in use is wasted memory. 

If you allocate private heaps or 
otherwise suballocate in dynamic seg¬ 
ments, free or at least shrink the seg¬ 
ments when not in use. And at a finer 
granularity, avoid generating garbage 
(leakage) by failing to free memory. 
Whenever you code a call that allocates 
memory, immediately write the cor¬ 
responding call to free the memory: 
garbage-free coding takes discipline. 


Low Memory Conditions 

Many windows applications become 
fragile when memory is low. Centralized 
error-handling with nonlocal exit helps 
prevent the common problem of failing 
to check the result of an allocation call. 

Listing 2 shows an example of such 
an error-handling mechanism. Win- 
Main () sets up a catch environment to 
which AllocMemO throws if an alloca¬ 
tion attempt fails. The result is that 
callers of AllocMemO need never test 
for allocation failure, since the function 
returns only if memory is allocated. 

A centralized handler permits more 
thorough handling than is possible 
when error handling is distributed 
throughout an application’s code. Mem- 
Alloc(), for example, retries after call¬ 
ing GlobalCompact(), and asks the user 
to try to free up some space. 

Another little-known clue your ap¬ 
plication gets when memory is scarce is 
the WMJOMPACTING message. You 
should always check for this message 
and free any noncritical memory imme¬ 
diately. 

A good tool for testing your 
application's low-memory robustness is 
the STRESS utility included with the 
Windows 3.1 SDK. Use STRESS, or roll 
your own with repeated calls to 
GlobalAlloc (), to detect low-memory- 
induced bugs in your application. 

GDI and User System 
Resources 

You should monitor free GDI and 
User heap space if your application 
dynamically allocates resources from 
either of these modules. In Windows 
3.0, pass either “USER" or “GDI” to the 
following function to determine free 
resources: 

WORD PASCAL 

GetSystemResources(LPSTR szModule) 

{ 

WORD wFree, wSize; 

DWORD dwlnfo = GetHeapSpaces( 
GetModuleHandle(szModule)); 
wSize = HIWORD(dwInfo); 
wFree = LOWORD(dwInfo); 
return L0W0RD((DWORD)wFree * 100 / 
wSize); 

) 

The above function makes use of the un¬ 
documented function GetHeapSpaces (). 
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Listing 2 


linclude <windows.h> 

LPVOID FAR PASCAL AllocMem(DWORD bytes); 

CATCHBUF CatchBuf; /* catch environment buffer */ 

int PASCAL WinMain(HANDLE hlnstance, 

HANDLE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) 

{ 

/* set initial block size to a value too large */ 

DWORD dwBlockSize = 100000000L; 

LPWORD lpWord; 

/* set up catch buffer; the Throw from AllocMem */ 

/* will result in a non-zero return from Catch below */ 
for (;;) 

{ 

if (Catch((LPCATCHBUF)CatchBuf) == 0) 
break; 

/* this code is executed when AllocMem fails */ 
if (dwBlockSize == 0) 

/* memory is totally exhausted */ 
return 0; 
else 

/* adjust block size after allocation fails */ 
dwBlockSize /■ 10; 

} 

lpWord = (LPWORD)AllocMem(dwBlockSize); 

/* the following dereference is always valid, since */ 
/* AllocMem never returns NULL. */ 
return *lpWord; 


/* Wrapper for Global Alloc that handles out-of-memory */ 
/* condition: this function never returns NULL. */ 

LPVOID FAR PASCAL AllocMem(DWORD bytes) 

{ 

HANDLE hMem = NULL; 

LPVOID IpResult; 

while (!(hMem = GlobalA1loc(GMEM_MOVEABLE, bytes))) 
if (GlobalCompact(bytes) < bytes) 

if (MessageBox(GetFocus(), "Out of memory. "\ 
"Close one or more applications, then "\ 
"select Retry, or select Cancel to exit.", 
NULL, MB_RETRYCANCEL | MBJCONHAND) 

!= IDRETRY) 

/* throw back to top-level (cancel) */ 

Throw((LPCATCHBUF)CatchBuf, 1); 

IpResult * GlobalLock(hMem); 

if (!1pResult) 

{ 

Global Free(hMem); 

/* throw back to top-level (cancel) */ 

Throw((LPCATCHBUF)CatchBuf, 1); 

) 

return IpResult; 

) 

/* End of File */ 


Out-of-memory Error Handler 


To use this function, include the following import in your 
module definition file: 

IMPORTS 

GetHeapSpaces=KERNEL. 138 

The function has the following prototype: 

DWORD FAR PASCAL 
GetHeapSpaces(HANDLE); 

Windows 3.1 provides a documented API for determining 
available system resources, namely GetFreeSystem- 
Resourcesf). 

Diagnosing UAEs 

Despite your best efforts in preventing memory bugs, you 
are certain to encounter at least a few UAEs while testing 
your application. If a UAE occurs when your debugger is 
loaded, you can usually find the culprit by examining the last 
executed instruction. If the code looks okay, look for invalid 
data passed into the function, and trace it back to its source 
with your debugger’s stack backtrace facility. 

UAEs are bound to occur in your application when you are 
not fortunate enough to have a debugger loaded. In this case, 
Dr. Watson (included in the Microsoft Windows 3.1 SDK) or a 
similar utility is the answer. If you, your testers, and your cus¬ 
tomers always have Dr. Watson loaded, then you will always 
have a stack backtrace for UAEs in your application. 

The keys to having a useful Dr. Watson log are to dis¬ 
tribute .syra symbol files with your executables (to testers), 
and to configure Dr. Watson to show you the information that 
will help you diagnose problems. Dr. Watson logs can become 
very large if you have the program dump everything it knows 
about the system state. On the other hand, if stack traces are 
too few or too short, you probably won't be able to diagnose 
UAEs. 1 include the following Dr. Watson options in my 
win.ini: 

[Dr. Watson] 

showinfo=disasm locals stack 
registers errorlog paramlog 
skipinfo=tasks modules 32bitregs 
dislen=16 
disstack=12 

The tasks and modules options produce huge and fairly use¬ 
less reports, so you probably want to disable these. A detailed 
stack trace lets you examine the code that crashed, local vari¬ 
able values, and function parameters of the current frame and 
callers - exactly what you would look at if you were in your 
debugger. 

Making Sense of a Dr. Watson Log 

Listing 3 shows a contrived buggy Windows application, 
and Figure 3 shows the Dr. Watson log that results when you 
run the program and it UAEs. The Dr. Watson log shows sym¬ 
bols only for addresses of exported functions, and only if a 
.sym file of the same name as the module resides in the 
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directory from which the module was loaded. Use MAPSYM to 
produce such a .sym file. 

As you can see in Figure 3, Dr. Watson diagnoses the prob¬ 
lem as a NULL selector read. Looking at the disassembly of the 
instructions prior to the fault (Stack Frame 0), the invalid selec¬ 
tor comes from [bp+08] - the second parameter to add_in- 
direct(). Backtracing to Stack Frame 1, you can see the NULL 
value eight bytes into UinMain ()'s stack frame. Moreover, you 
can see the NULL in local variable p at [bp-06], which is the 
original source of the UAE. By the way, Dr. Watson always 
disassembles offsets from base registers as positive values. So 
the [bp+fe] shown in Stack Frame 1, for example, is really 
[bp-02], or local variable a with value 1. 

Summary 

Determining the cause of memory bugs is often a need¬ 
lessly painful process. With a few simple techniques and an 
attitude of defensive coding, you can save yourself a lot of 
grief. 

I hope this article will help you avoid all-night vigils spent 
chasing a bug caused by a simple off-by-one allocation or a 
double-free. But if such a bug does creep in, I hope to have 
armed you with some techniques to use when, at 5:00 a.m, 
you come face-to-face with the pesky thing, a 


Figure 3 

Dr. Watson 0.73 Failure Report 

Sun Mar 15 14:40:03 1992 

L1STING3 had a 'Null Selector (Read)' fault at LISTING3 

1:194 


LISTING3 1:194 add ax, es:[bx] 

CPU Registers (regs) 


ax=0001 bx=0000 cx=0000 dx=0060 si=0060 di=0060 

ip=0194 sp=146e bp=147e 0- D- 

1+ S- Z- A+ P- C- 

cs = 12b5 2df230:01ef Code Ex/R 

ss = 12c5 106090:24af Data R/W 

ds = 12c5 106090:24af Data R/W 

es = 0000 0:0000 Null Ptr 

Stack Dump (stack) 


Stack Frame 0 is LISTING3 cs:ip 

12b5:0194(1) ss:bp 

12c5:147e 


ss:1460 

56 24 

ss:1470 Id 10 01 00 Od 00 7c 02 

94 01 b5 12 12 32 

12b5:0189 8b ec 

mov bp, sp 

12b5:018b c4 5e 04 

les bx, [bp+04] 

12b5:018e 26 8b 07 

mov ax, es:[bx] 

12b5:0191 c4 5e 08 

les bx, [bp+08] 

(LISTING3: add indirect+OOOc) 


12b5:0194 26 03 07 

add ax, es:[bx] 

12b5:0197 eb 00 

jmp short 0199 

12b5:0199 5d 

pop bp 

12b5:019a c3 

retn 

Stack Frame 1 is LISTING3 cs:ip 

12b5:017f(1) ss:bp 

12c5:1490 


ss:1470 

90 14 

ss:1480 7f 01 8e 14 c5 12 00 00 

00 00 00 00 00 00 01 00 

12b5:0177 16 

push ss 

12b5:0178 8d 46 fe 

lea ax, [bp+fe] 

12b5:017b 50 

push ax 

12b5:017c e8 0009 

call near 0188 

(LISTING3:WINMAIN+0023) 


12b5:017f 83 c4 08 

add sp, 08 

12b5:0182 eb 00 

jmp short 0184 

12b5:0184 c9 

leave 

12b5:0185 c2 000a 

retn 000a 

Dr. Watson Debugging Output 
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Listing 3 

/* Contrived buggy example to illustrate */ 

/* diagnosing UAE with Dr. Watson. */ 

#include <windows.h> 

/* export all functions during debugging */ 

/* to aid Dr. Watson UAE diagnosis */ 

#if DEBUG 

Idefine DBG _export 
lelse 

Idefine DBG 
lendif 

int DBG add_indirect(LPWORD, LPWORD); 

int PASCAL WinMain(HANDLE hlnstance, 

HANDLE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) 

{ 

WORD a = 1; 

LPWORD p = NULL; 

return add_indirect(&a, p); 

} 

int DBG add_indirect(LPWORD a, LPWORD b) 

( 

return *a + *b; 

} 

/* End of File */ 

Windows Application that UAEs 
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Intercepting 


DLLs have always represented an opportunity 
for debugging Windows applications. Petzold’s 
book demonstrates how to construct a DLL of alias 
functions to intercept calls to Windows functions. 
By linking such a debugging DLL to your applica¬ 
tion, you could intercept your own calls to the 
Windows API in order to print debugging messages 
or check for bad parameters - an especially useful 
ability in the days before Windows 3.1’s improved 
error checking. 

The drawback of Petzold's method is that it is 
local to your application and established at link 
time, not runtime. You have to link in the "inter¬ 
ceptor" DLL to do your debugging and then link 
with the "normal” DLL to remove the debugging 
facility, and you can only intercept calls your ap¬ 
plication makes. What if you could intercept calls 
to any DLL function made from any application? 
This could be useful, not only for debugging, but 
also for a variety of specialized applications. In this 
article, I demonstrate how to intercept all calls 
made to a DLL function, regardless of the applica¬ 
tion making the call. 

How It Works 

The basic idea behind globally intercepting DLL 
function calls is to do what a debugger does - 
patch the function you want to intercept. A 
debugger would probably patch the function by 
replacing its first opcode with a breakpoint op¬ 
code. Then, any call to that function would 
produce a breakpoint interrupt, which would route 
control to the debugger's interrupt handler. 


Timothy Adams is the author of HOTWin. He can be reached on 
CompuServe at 70571,454. 
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Debugging 


DLL Function Calls 


Timothy Adams 


I take a slightly different approach by patching in a jump 
to the intercept function. The intercept function is then 
responsible for replacing the original opcodes and returning to 
the function being intercepted. The technique is almost as 
simple as it sounds, but you have to take into account 
protected memory and discardable code segments. 

Patching the DLL Function 

Patching a DLL function requires you to read and write 
code segments - you have to read the bytes you are going to 
patch (to save them so you can put them back later) and you 
have to write to insert the instructions to jump to your inter¬ 
ceptor function. Since Windows functions reside in execute- 
only segments, you have to create a selector that refers to 
the same segment but has read/write attributes. 

To create a read/write far pointer to the segment contain¬ 
ing the function you want to patch, start with the function's 
selector. To get the code selector of a function, pass the ad¬ 
dress of that function to the HIWORDf) macro (included in win¬ 
dows, h). You want to leave that selector execute-only, so the 
next step is to allocate another selector with exactly the same 
attributes, by calling AllocSelector(). 

AllocSelector() simply allocates a new selector that is a 
duplicate of the one you pass it. That still does not let you 
read or write the code segment, but you can pass this new 
selector to ChangeSelector() to change it into a data 
(read/write) selector. Here is how you would obtain a 
read/write selector to the function WinExecf): 

WORD DataSel, CodeSel; 

CodeSel = HIWORD(WinExec); 

DataSel = AllocSelector(CodeSel); 

DataSel = ChangeSelector( 

CodeSel, DataSel); 

ChangeSelector() has a couple of problems you have to be 
aware of. First, the function was incorrectly named Presto- 
ChangoSelector() in the Windows 3.0 libraries. That problem 


is fixed in Windows 3.1, so the best workaround is code like 
this: 

#include <windows.h> 

#ifndef WIN31 
#define ChangeSelector 
PrestoChangoSel ector 
lendif 

Second, the SDK documentation has the parameters to the 
function interchanged. The first argument is the source, not 
the destination selector, and vice versa. 

The Intercept Example 

To demonstrate how to globally intercept DLL calls, I have 
written a sample program that intercepts all calls to the Win¬ 
dows function WinExec(), which resides in the Windows ker¬ 
nel. As applications call WinExec() to launch other programs, 
the intercept code in the sample application adds each path 
to a listbox. 

The example application consists of two 
parts: inter.exe and patch.dll. inter.exe dis¬ 
plays a dialog box and makes the calls to patch 
and unpatch the function being intercepted. 
patch.dll contains the patching and unpatch¬ 
ing code and the interceptor function. 

Listing 1 contains patch.c, the 
code to patch and unpatch Win- 
Exec(). Note that Patch () creates a 
data alias to its own code segment 
as well as WinExec()'s code seg¬ 
ment. It uses the former alias to 
read a copy of an instruction that 
jumps to the interceptor function. 

Patch () uses those bytes to replace 
the beginning of Win- 
Exec ()’s code. 
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Listing 1 (patch.c) 

/* Patch.c Contains Patch functions for Inter.exe */ 

Idefine WINDOWS 
fdefine “WINDLL 
fifndef WIN31 

Idefine ChangeSelector PrestoChangoSelector 
lendif 

linclude <windows.h> 
linclude <memory.h> 
linclude <string.h> 
linclude <dos.h> 

VOID FAR PASCAL Patch(HWND hWndList); 

VOID FAR PASCAL UnPatch(VOID); 

WORD FAR PASCAL MyWinExec (LPSTR IpPath.int show); 

WORD FAR PASCAL WinWinExec (LPSTR IpPath.int show); 
int FAR PASCAL LibMain(HANDLE hlnst.WORD wDataSeg.WORD cbHeapSize, 

LPSTR IpszCmdLine); 

int FAR PASCAL WEP (int bSystemExit); 

Idefine CPYBYTES 5 /‘Number of Bytes to Copy*/ 

BYTE btWinexec[6]; 

HWND hWndList; 

LPSTR IpPatch.IpWinexec; 

WORD selPatchRW.selWinExecRW.selWinExec; 

/* Installs a Patch in the Winexec Function. */ 

VOID FAR PASCAL Patch(HWND hwndlist) 

( 

WORD offst; 
hWndList=hwndlist; 

sel PatchRW=Al 1 ocSelector(HIWORD(Patch)); 

ChangeSelector(HIWORD(Patch).selPatchRW); 

_asm mov ax,offset patchcode 

_asm mov offst.ax 

lpPatch=(LPSTR)MAKELONG(off$t,selPatchRW); 

selWinExec=HIWORD(WinWinExec); /‘Get Selector of WinExec Function*/ 

GlobalPageLock(selWinExec); /‘Lock Segment*/ 

selWinExecRW=AllocSelector(selWinExec); /‘Get New selector*/ 
ChangeSelector(selWinExec.selWinExecRW); /‘Change Code Selector to R/W*/ 
/‘Setup Pointer to WinExec Function*/ 

1pWinexec=(LPSTR)MAKEL0NG(L0W0RD(WinWinExec).selWinExecRW); 

_fmemcpy (btWinexec,lpWinexec,CPYBYTES); /‘Save first 5 bytes of Winexec*/ 
_fmemcpy (lpWinexec,IpPatch,CPYBYTES); /* Patch the WinExec Function*/ 

return; 
patchcode: 

asm jmp MyWinExec ;Code Copied to Winexec Function 

} 

I***************************************************** 

MyWinExec Intercept Function 

1) The Windows WinExec Function is Called. 

2) Patch code is Executed in the WinExec function. (Jmp to MyWinExecO). 

3 Debug Output is done to the Listbox. 

3) WinExec is Unpatched. 

4) WinExec is then called. 

5) WinExec is then repatched for next call. 

******************************************************I 

WORD FAR PASCAL MyWinExec (LPSTR IpPath.int show) 

( 

char szbuff [200]; 
int result; 

wsprintf (szbuff,"Path %s",(LPSTR)1pPath); 

SendMessage (hWndList,LB_ADDSTRING,0,(LONG)(LPSTR)szbuff); 

_fmemcpy (lpWinexec,btWinexec,CPYBYTES); /‘Unpatch and Call*/ 
result=WinExec(lpPath,show); 

_fmemcpy (lpWinexec,1pPatch,CPYBYTES); /‘Repatch For Next Call*/ 
return result; 

} 


/‘Save Handle to ListBox*/ 

/*Get Selector of Patch*/ 

/‘Change Selector to Read Write*/ 
;Setup Pointer to Patch Code 


VOID FAR PASCAL UnPatch(VOID) 

( 

_fmemcpy (lpWinexec,btWinexec,CPYBYTES); 
GlobalPageUnlock(selWinExec); 
FreeSelectorfselPatchRW); 
FreeSelector(selWinExecRW); 

) 


/* Unpatch for shutdown*/ 


Code to Patch/Unpatch DLL Function 


Also note that Patch() calls Global- 
Page Lock () to keep Windows from dis¬ 
carding the code segment containing 
WinExecO. This is necessary because 
Windows could decide to discard Win- 
Exec ()'s code segment in order to free 
up memory. Windows would reload 
WinExecO’ s code segment the next 
time an application called it, but 
Patch ()'s patch would no longer be in 
place. The UnPatch () function simply 
puts back WinExecO’ s original bytes, 
unlocks WinExecO' s code page, and 
frees up the selectors that Patch () allo¬ 
cated. 

MyWinExecO is prototyped exactly 
like the real WinExecO. When some 
application calls WinExecO, the patch 
code is executed and does a far jump 
to MyWinExecO. MyWinExecO adds the 
path to the list box and then unpatches 
WinExecO and calls it. MyWinExecO 
saves the return value, repatches Win¬ 
ExecO, and then returns the result to 
the caller. 

Listing 2 contains inter, c, the main 
application code that establishes the 
dialog box and calls Patch () and Un- 
Patch(). Figure 1 lists all the miscel¬ 
laneous files you need to build the 
sample application. 

Summary 

The release of Windows 3.1 and the 
accompanying toolhelp.dll provide a 
more documented method to perform 
steps necessary to intercept DLL calls 
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Listing 1 — Cont’d 

int FAR PASCAL LibMain(hInst, wDataSeg, cbHeapSize, lpszCmdLine) 
HANDLE hlnst; 

WORD wDataSeg; 

WORD cbHeapSize; 

LPSTR lpszCmdLine; 

( 

return 1; 

} 

int FAR PASCAL WEP (bSystemExit) 
int bSystemExit; 

f 

return(1); 

) 

/* End of File */ 


Listing 2 (inter.c) 

j ★★*★★**★**★**★*★★★★★★★★★★★★★*★*★*****★***★*★★****★*★★★★★★**★*★★*★* 

Inter.c Intercepting dll functions demonstration. 

(c) Timothy Adams 1992 
Windows SDK V. 3.0 and 3.1 
Microsoft C V. v6.0 
Windows V. 3.0 and 3.1 

Idefine _WIND0WS 
linclude <windows.h> 

VOID FAR PASCAL Patch(HWND hWndList); 

VOID FAR PASCAL UnPatch(VOID); 

int PASCAL WinMain(HANDLE, HANDLE, LPSTR, int); 

BOOL FAR PASCAL InterDlgProc(HWND hDlg.WORD message,WORD wParam.LONG IParam); 

/‘Intercept Dig Box Defines*/ 

Idefine IDDJNTER 100 

Idefine IDLJNTER 101 

HANDLE hlnst; 

HWND hWndlnter; 

int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow) 

HANDLE hlnstance; 

HANDLE hPrevInstance; 

LPSTR lpCmdLine; 
int nCmdShow; 

( 

FARPROC lpfnlnter; 

MSG msg; 

hlnst=hlnstance; 
if (hPrevInstance) 
return 0; 

lpfnInter=MakeProcInstance(InterDlgProc,hlnst); /‘Open the Dialog Box*/ 
hWndInter=CreateDialog(hInst,MAKEINTRESOURCE(IDD_INTER),NULL, lpfnlnter); 

Patch(GetDlgItem(hWndInter,IDL INTER)); /‘Patch WinExec Function*/ 

while (GetMessage(&msg,NULL,NULL, NULL)) 

( 

if (IsDialogMessage(hWndInter,&msg)) 
continue; 

TranslateMessage(&msg); 

DispatchMessage(Smsg); 

) 

FreeProcInstance(lpfnlnter); 

UnPatch(); /‘UnPatch WinExec Function*/ 

return (msg.wParam); 

) 
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Listing 2 — Cont’d 


BOOL FAR PASCAL InterDlgProc(HWND hDlg.WORD message.WORD wParam.LONG IParam) 

{ 

int nWidth.nHeight; 

RECT rc; 

switch (message) 

{ 

case WMJNITDIALOG: 

/‘Center Window*/ 

nWidth=GetSystemMetrics(SM_CXSCREEN); 
nHeight=GetSystemMetrics(SM_CYSCREEN); 

GetClientRect(hOlg,&rc); 

SetWindowPos (hDlg,NULL, 

nWidth/2-rc.right/2, 
nHeight/2-rc.bottom/2, 

0,0,SWP_NOSIZE); 

return TRUE; 
case WM_COMMAND: 
switch (wParam) 

f 

case IDCANCEL: 

DestroyWindow(hDlg); 

PostQuitMessage(O); 
return TRUE; 

) 

) 

return FALSE; 

} 

/* End of File */ 


PATCH.OEF 


Listing 3 (patch.def) 

Module definition file 


LIBRARY PATCH 

Description 'Intercepting dll functions (c) Timothy Adams 1992 ' 
EXETYPE WINDOWS 

FIXED 

FIXED SINGLE 


CODE PRELOAD 

DATA PRELOAD 

HEAPSIZE 5000 
EXPORTS 
WEP 

MYWINEXEC 
PATCH 
UNPATCH 
IMPORTS 

WINWINEXEC=KERNEL.166 


@1 RESIDENTNAME 

@2 

@3 

@4 


Module Definition File for patch.dll 


Listing 4 (inter.def) 


; INTER.DEF Module definition file 
NAME INTER 

DESCRIPTION 'Intercepting dll functions (c) Timothy Adams 1992 
EXETYPE WINDOWS 

STUB 'WINSTUB.EXE' 

CODE PRELOAD MOVEABLE DISCARDABLE 

DATA PRELOAD MOVEABLE 

HEAPSIZE 5000 

STACKSIZE 5120 

EXPORTS 

INTERDLGPROC @1 


Module Definition File for inter.exe 
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(Matt Pietrek's article in this issue, "Writ¬ 
ing a Windows Debugger," discusses 
how Windows debuggers can use tool- 
help.dll). Although the method 
presented in this article is not sanc¬ 


tioned by Microsoft or guaranteed to 
work in future versions of Windows, it 
works with both Windows 3.0 and Win¬ 
dows 3.1 and does not require the 
presence of toolhelp.dll. □ 



Graphics Interface (TGI) 


CGA, Hercules, EGA, VGA, VGA X mode 
and Super VGA. 256 colors. 800 x 600 & 
1024x 768. Fast scrolling. Autodetection. 
Supports cards by Ahead, Ati, C&T, 
Everex, Trident, Tseng, Video 7 and more. 
BGI function compatible. Fast bit image 
fonts, 40 included. Full source code in¬ 
cluded. $ 99 

Virtual Memory Manager (VMM) 
Uses XMS, EMS and hard drive. Source 
code included. $ 99 

Font editor & Icon editor 


Includes 200 fonts and application 
source. $ 99 



Graphical User Interface (GUI) 

Fast, flexible and easy to use. Includes 
menus, mouse support, buttons, file 
selector, dialogues, pick lists world co¬ 
ordinates and much, much more. Struc¬ 
tured and OOP interface provided. In¬ 
cludes source for GUI and runtime for 
TGI & VMM $ 99 



TEGL Systems Corporation 


780-789 West Pender Street 
Vancouver, B.C. Canada V6C 1H2 
Phone (604) 669-2577, Fax (604) 688-9530. 
Shipping & Handling $15 
($30 outside Canada & US) 

Visa & Mastercard accepted. 

Works with Borland, Intel, Metaware, Microsoft, 
WATCOM, Topspeed, Turbo & Zortech C. 
Turbo Pascal & Stony Brook Pascal+. Does 
not require or work with Microsoft Windows. 

Trademarks are property erf their respective holders. 


Figure 1 

File 

Description 

Listing 1 (patch.c) 

Code to patch/unpatch DLL function. 

Listing 2 (inter.c) 

Main program. 

Listing 3 (patch.def) 

Module definition file for patch.dll. 

Listing 4 (inter.def) 

Module definition file for inter.exe. 

Listing 5 (inter.rc) 

Dialog box description. 

Listing 6 (inter.mak) 

Makefile for project. 

Files for DLL Intercept Program 


Listing 5 (inter.rc) 

/* INTER.RC Resource File */ 
finclude <windows.h> 

100 DIALOG 79, 72, 243, 121 

STYLE DS_M0DALFRAME | WS_P0PUP | WS_VISIBLE | WS_CAPTION | WS SYSHENU 
CAPTION “Interceptions” 

FONT 8, “Helv” 

BEGIN 

LISTBOX 101, 4, 4, 234, 100, WS_VSCR0LL 

DEFPUSHBUTTON "Close", IDCANCEL, 102, 105, 40, 14, NOT WS_TABST0P 
END 

Dialog Box Description 


Listing 6 (inter.mak) 

#. 

# INTER.MAK Make File 

t . 

ALL: inter.exe 

DLLFLAGS ■ -c -Asnw -Gsw -qc -Od -Zpe 
APPFLAGS « -c -AS -Gsw -qc -Od -Zpe 

inter.res: inter.rc 
rc -r inter.rc 

patch.obj: patch.c patch.h 
cl $(DLLFLAGS) patch.c 

patch.lib: patch.obj patch.def 
implib patch.lib patch.def 

inter.obj: inter.c inter.h 
cl $(APPFLAGS) inter.c 

patch.dll: patch.obj patch.def 

link J(LINKFLAGS) patch libentry , patch.dll,HW, /NOE /NOD sdllcew libw, 
patch.def 

rc patch.DLL 

inter.exe: inter.obj inter.def 

link $(LINKFLAGS) inter,,,/NOE /NOD patch libw slibcew, inter.def 
rc inter.res inter.exe 

inter.exe: inter.res 
rc inter.res inter.exe 

Makefile for Project _ 
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3.1’s Internal Window 
Structure 

(plus Editltem tricks, linear memory 
locations, tabbing, and more) 

Q ln the February issue of Windows/DOS Developer's Journal you examined how 
to superclass the ListBox component of a ComboBox. I am writing you with the 
hope of getting you to continue the discussion and to explain how to tap into the 
Editltem component of a Simple or DropDown ComboBox. 

What I’m currently looking to achieve is to be able to detect double-clicks (for 
both the left and right buttons). At a later date, I might also want to be able to 
intercept the keystrokes. 

Richard L. Rosenheim 
5712 North Casa Blanca Road 
Paradise Valley, AZ 85253 

A Unlike the ListBox control of a ComboBox, the Editltem is a child of the Combo¬ 
Box window (the ListBox is a child of the desktop window). Thus one can ex¬ 
tract the edit handle without resorting to the use of undocumented features (as was 
necessary in the solution presented in the February 1992 issue, 3:2, p. 41). It is 
preferable to use a legal approach, since you have a much better chance of your 
code surviving a new version of Windows. 

Given a ComboBox window handle, the Editltem window handle can be extracted 
using the routines GetUindowf) and GetClassNamef). GetUindowf) is used to 
enumerate the children of the ComboBox. The string returned by GetClassNamef) 
can be compared with “edit,” the class name of the Editltem. 

After obtaining the Editltem’s window handle, you can subclass the window using 
GetUindowLongf) and SetClassLongO. These routines get and set the window pro¬ 
cedure for a given window when supplied with the index GNLJ/NDPROC. You then 
need to export your subclasser in your linker module definition file and create an 
instance procedure handle with MakeProcInstance(). Use GetUindowLongf) to ob¬ 
tain the original window procedure, which your subclasser will call to handle mes¬ 
sages the subclasser does not, and SetUindowLongf) to install your subclasser. Don't 
forget to free the instance procedure handle when the window is destroyed. This 
can be conveniently taken care of in the subclasser itself, when it receives the 

Paul Bonneau ^destroy message. 

Listing 1 presents code for LpfnSubclassComboEdit(), a routine that, given a 
ComboBox window handle and the instanced address of a window procedure, will 
subclass the Editltem with the given procedure. Listing 2 is the header file interface, 



Send questions to Paul via Internet 
as bonneau@hyper.hyper.com or in 
care of this magazine at 1601 W. 
23rd St., Suite 200, Lawrence, KS 
66046-2743. 


Paul Bonneau is the senior software design engineer for Hypercube, Inc., #7-419 Phillip 
St, Waterloo, Ontario, Canada, N2L 3X2. His current project is HyperChem, a molecular 
modelling software package for Windows. Paul has been developing Windows ap¬ 
plications for 5 years. Much of his expertise was gained at Microsoft, where he imple¬ 
mented a library module used by all of Microsoft's major Windows applications. 





















and Listing 3 presents a sample subclasser that just displays a 
string within the Editltem whenever the user double-clicks 
with the left or right button. This code will work for both 
versions 3.0 and 3.1 of Windows. 

Q l am trying to access linear memory location CA00-.0000 
inside a protected-mode Windows program. I need to do 
this because this location is used to talk to a hardware adapt¬ 
er that we are using. Since Windows runs in protected mode, 
it is not an easy task. I would appreciate any suggestions you 
may have about this problem. 


Messagef). If it returns true, the message was translated into 
one or more DialogBox navigation messages, and should not 
be passed to TranslateMessage() or DispatchMessage(). For 
example, the ListBox will never see a WM_KEYDOWN for vk_tab, 
since IsDialogMessage() will translate it into a call to Set- 
Focus () for the control to tab to. 

Q Since I presented the internal structure of a window in 
the December 1991 issue (2:12, p.11), several people 
have asked about the internals under version 3.1. So let's see 
what’s changed under the hood. 


A Luckily, the kernel exports nine symbols that can be 
used to access linear memory locations. Each of these 
symbols begins a segment that maps to the corresponding 
linear address. Table 1 gives the names of the symbols and 
the linear address and range of each. All numbers in Table 1 
are in hexadecimal. The actual selectors listed are machine 
dependent: what's important are the linear memory locations 
they address. The information in the table was obtained with 
the Windows kernel debugger dg (dump GDT entries) com¬ 
mand. 

So, to access CAOOiOOOO (i.e., linear address OOOCAOOO): 
extern WORD _C000H; 

LPSTR lpb = (LPSTR)MAKELONG(OxAOOO, (WORD)&C000H)); 

Note that only one underscore is used to name the symbol 
from a C program, since the compiler automatically prepends 
an underscore to all cdecl symbols. 

Q l have written a simple application that works fine with 
a mouse, and am now adding keyboard support. The 
application basically consists of a single DialogBox which con¬ 
tains two GroupBoxes. Each GroupBox contains a ListBox and a 
couple of PushButtons. I initially set the focus to one of the 
ListBoxes. Keyboard scrolling etc. works fine within the List- 
Box. I have defined the ListBoxes and PushButtons with 
US_TABSTOP in the .rc file and expected TAB to move the 
focus along to the next control; however, nothing happens. 

I modeled my application along the lines of hexcalc in 
Petzold - i.e., no dialog procedure, just a regular window pro¬ 
cedure. I see from TD that the KEYDOUN etc. messages are 
going to the ListBox window that has the focus. I don’t have a 
separate window procedure for the ListBox, so I never “see" 
the keyboard messages. 

I was kind of expecting Windows to manage the tabbing 
between controls. Was that wrong, or is it not working be¬ 
cause I haven’t got a regular DialogBox procedure? 

Jeff Fulton 
jefff@sequent.com 

A The routine IsDialogMessage() intercepts keyboard 
input for a DialogBox and translates it into the cor¬ 
responding set of messages to achieve keyboard navigation. 
Use of this magic routine is not restricted to true DialogBoxes 
(windows belonging to the DialogBox class); it can also be 
called for any window that possesses child controls. 

Call IsDialogMessage() from your main loop after extract¬ 
ing a message from the queue with PeekMessagef) or Get- 


A First off, I would like to make clear that I have gleaned 
the contents of the new window structure (let’s refer to 
it as if it were typedef UND for simplicity) by poking around 
with the debugger. As far as I know, Microsoft does not make 
this structure public, and there is no guarantee that I haven’t 
misinterpreted something. 

As mentioned in the December article, WNDs live within the 
USER DLL's default data segment. This data segment contains 
a local heap, and each UNO is allocated from that heap using 
Local Alloc (LMEMJIXED | LMEM_ZEROINIT, 0x003C). The 
result is a near pointer within the heap, since the memory 
was allocated using the LMm_FIXED flag. In the retail version 
of Windows, this WND pointer within the USER default data 
segment is exported as the window handle. In the debug ver¬ 
sion, four extra bytes of memory are allocated and four is 
added to the pointer to create the window handle value. The 
first four bytes of the local block are probably used for inter¬ 
nal consistency checks. Regardless of the version, the window 
handle is used internally as a pointer. This clever trick isolates 
the debugging information from the rest of Windows. 


Figure 1 
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A Sample Window Tree 
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One can obtain a far pointer to a UND by using the follow¬ 
ing code fragment- 

WND FAR * lpwnd; 

HINSTANCE hinsUser; 

hinsUser = LoadLibrary("user.exe“); 
lpwnd = HIW0RD(GlobalLock(hinsUser)); 

This relies on the facts that the module handle returned by 
LoadLibraryO is nothing more than the level 3 selector of 
the USER default data segment, and that a global handle is 
implemented as the level 3 selector of the referenced seg¬ 
ment. However, it seems likely that version 3.1 is the last 
major release of Windows to permit this access to private 
data structures. The Win32 LoadLibraryO call returns a uni¬ 
que value to each 32-bit application making the call. In addi¬ 
tion, there is no guarantee that USER will continue to exist as 
a module. The bottom line is that while knowing what a UND 
looks like can help in your debugging effort, don't rely on it in 
your code, as it will be a barrier to porting to the Win32 API. 

Listing 4 is the source description for type UND. The first 
four fields are used to maintain the window tree. Siblings in 
the tree lie on a singly-linked list (via the hwndNextSibling 
field), from first to last. The child-parent relationship is doubly- 
linked (via hwndFirstChild and hwndParent). As new siblings 
are created, they are added at the front of the sibling list. As 
you can see, calling GetUindowf) with GU_HUNDLAST or 
GU_HUNDPREV (to find the last or previous sibling window) can 
be an expensive operation if the list of siblings is large. 

Figure 1 illustrates a sample window tree for the simplified 
case of an application with one main window and one dialog, 
with the dialog possessing one child control. Popup windows 
are linked to their owners with the hwndOwner field. When the 
owner is iconized, the popup is hidden. When the owner is 
disabled and the popup is activated, its owner is brought to 
the top of the window stack. 

The next two fields describe the position of the window 
and its client area. The rectUindow field is the position of a 
window in the client area of its parent. Since the parent of a 
top-level or popup window is the desktop window, these 
values are equivalent to screen coordinates. The rectClient 
field is the position of the window's client area, in its own 
client coordinates. Thus the value of rectClient.left and 
rectClient. top is usually 0. 

The hmemQueue field is the selector of a small segment that 
describes a module's message queue. Offset 2 in the hmem¬ 
Queue segment is the selector of the module's program 
database segment, another small segment containing further 
task state data. The hmemClass field is the local address (in the 
USER data segment) of the class to which the window 
belongs. The next field, hins, is the level 3 selector of the 
module's default data segment. 

A window’s window procedure is stored both in its UND (in 
the IpfnUndProc field) and in the corresponding class struc¬ 
ture. This duplication allows an individual window to be sub¬ 
classed without requiring subclassing for every other window 
of the class. The dwStyle and dwExStyle fields represent 
(more or less) the style flags passed to CreateUindow() or 
CreateUindowExf) via the parameters of the same name. 
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Table 1 

Symbol Name 

Selector 

Selector Type 

Linear Address 

Size 

Comments 

OOOOh 

100D 

Local 

00000000 

10000 

Interrupt table 

0040h 

0040 

Global 

00000400 

300 

ROM BIOS Variables 

AOOOh 

101D 

Local 

000A0000 

10000 

Video memory (modes 0D-13) 

BOOOh 

1025 

Local 

000B0000 

10000 

Video memory (mode 07) 

B800h 

102D 

Local 

000B8000 

10000 

Video memory (modes 00-06) 

C000h 

1035 

Local 

ooocoooo 

10000 

Installable ROM (Video BIOS) 

DOOOh 

103D 

Local 

000D0000 

10000 

“ n 

EOOOh 

1045 

Local 

000E0000 

10000 

ROM BIOS (PS/2 not 25 or 30) 

FOOOh 

1015 

Local 

000F0000 

10000 

ROM BIOS (PC/XT/AT, PS/2 25 & 30) 


The handle to a window's menu is kept in the hmnu field. If 
the window is a child, this field is used to store its control ID. 
Therefore, a child window cannot possess a menu bar. The 
hmemTitle field is the address of a local block of memory in 
one of USER'S private extra data segments. A data segment 
other than the default is used here, presumably to offload 
demands on the already overloaded USER default data seg¬ 
ment. Note that a local heap is restricted to a maximum size 
of 64Kb. Since all UNDs are in the USER default data segment, 
the less it is used for other ancillary storage, the more win- 


Listing 1 (comboed.c) 

♦include <windows.h> 

♦include "comboed.h” 

FARPROC 

LpfnSubclassComboEdit(FARPROC lpfn, HWND hwndCombo) 

j*****************************************************i 


/* — If the given ComboBox contains an Editltem, */ 
/* subclass it with the given window proc. */ 
/* — Return the Editltem's original window */ 
/* procedure, or NULL for failure. */ 
/* — lpfn : Procedure instance of subdasser. */ 
/* — hwndCombo : ComboBox window handle. */ 


/*★*****************★*********************************/ 

{ 

HWND hwndChild; 

FARPROC lpfnEdit; 

/* Loop over all the child windows of the */ 

/* ComboBox. Stop if we find an Editltem. */ 
for (hwndChild ■ GetWindow(hwndCombo, GW CHILD); 
hwndChild != NULL; 

hwndChild = GetWindowfhwndChild, GW_HWNDNEXT)) 

( 

char szClass[10]; 

GetClassName(hwndChild, szClass, 
sizeof szClass); 

if (lstrcmpi(szClass, "edit”) *■ 0) 
break; 

) 

if (hwndChild == NULL) 

return NULL; /* Must be CBS_DR0PD0WNLIST. */ 
lpfnEdit * 

(FARPROC)GetWindowLong(hwndChi1d, GWL_WNDPR0C); 
SetWindowLong(hwndChi1d, GWL_WNDPR0C, (LONG)1pfn); 
return lpfnEdit; 

1 

/* End of File */ 


Subclass the Editltem of a ComboBox 


dows can be created. It seems strange then that the hmem- 
Scroll field, which is used to reference the state variables of 
non-client ScrollBars, should point to memory inside the USER 
data segment. I don't know why Microsoft did not move it to 
another segment as well. The same goes for hmemProp, the 
head of the property list, which also points to a block of local 
memory inside the USER default data segment. 

The last field in the UND is the beginning of the user- 
defined area. This is where extra storage accessible via a non¬ 
negative index to Get/SetWindowUord() and Get/SetWindow- 
Long() is kept. The size of this area is determined when the 
class is registered, via the cbUndExtra field of the class struc¬ 
ture, so the size of a UND is not fixed. 
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Listing 3 (tstcombo.c) 


♦include <windows.h> 

♦include "comboed.h" 

FARPROC lpfnEdit; /* Original Editltem wind. proc. */ 
FARPROC lpfnFilter; /* Subclass for above. */ 

/* Subclasser for ComboBox's Editltem. Don't forget */ 
/* to export in .def file! */ 

LONG FAR PASCAL EditSubclasser(HWND, WORD. WORD, 
DWORD); 


LONG FAR PASCAL 

Edit$ubclasser(HWND hwnd, WORD wMessage, WORD wParam, 
DWORD 1wParam) 

/* -- Window proc to subclass the Editltem of a */ 
/* ComboBox. */ 

/* -- Display a string with double-clicked. */ 

/* — Free our proecudure instance handle when done. */ 

I *****************************************************I 


VOID 

TestComboEdit(HWND hwndCombo) 

jj 

/* — Install a subclasser for the given ComboBox to */ 

/* demonstrate the LpfnSubclassComboEdit() */ 

/* routine. */ 

/* — hwndCombo : ComboBox window handle. */ 

{ 

/* Create a procedure instance of the subclasser. */ 
lpfnFilter = MakeProcInstance( 

(FARPROC)EditSubcl asser, 

(HANDLE)GetWindowWord(hwndCombo, GWW_HINSTANCE)); 
if (lpfnFilter == NULL) 
return; /* Failure. */ 

/* Attempt to install the subclasser. */ 
lpfnEdit = 

LpfnSubclassComboEdit(lpfnFilter, hwndCombo); 
if (lpfnEdit == NULL) 

FreeProcInstance(lpfnFilter); /* Failure. */ 

1 
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publications, inc. 


BOOL fHandled; /* Handled the message? */ 

switch (wMessage) 

{ 

default: 

fHandled ■ FALSE; 
break; 

case WM_LBUTTONDBLCLK: 

SetWindowText(hwnd, ''Left double click"); 

fHandled = TRUE; 

break; 

case WM_RBUTTONDBLCLK: 

SetWindowText(hwnd, "Right double click"); 

fHandled = TRUE; 

break; 

case WM_DESTROY: 

/* Free the procedure instance and restore */ 
/* the origial window proc. */ 
FreeProcInstance(lpfnFiIter); 

SetWindowLong(hwnd, GWL_WNDPROC, 

(LONG)1pfnEdit); 
fHandled = FALSE; 
break; 

) 


if (fHandled) 
return OL; 

/* Pass this off to the Editltem's original */ 
/* Window Procedure. */ 

return CallWindowProc(lpfnEdit, hwnd, wMessage, 
wParam, 1wParam); 

) 

/* End of File */ 


Exercise the LpfnSubclassComboEdit() Routine 


Listing 2 (combo.h) 


/* Prototype. */ 

FARPROC LpfnSubclassComboEdit(FARPROC, HWND); 
/* End of File */ 


Interface to Procedure to Install a Subclasser 
for the Editltem of a ComboBox 
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Listing 4 (win.h) 

typedef struct 
{ 


HWND 

hwndNextSibling; 

/* 

Offset 

0x0000 

*/ 

HWND 

hwndFirstChild; 

/* 

Offset 

0x0002 

*/ 

HWND 

hwndParent; 

/* 

Offset 

0x0004 

*/ 

HWND 

hwndOwner; 

/* 

Offset 

0x0006 

*/ 

RECT 

rectWindow; 

/* 

Offset 

0x0008 

*/ 

RECT 

rectClient; 

/* 

Offset 

0x0010 

*/ 

HANDLE 

hmemQueue; 

/* 

Offset 

0x0018 

*/ 

WORD 

wUnknownl; 

/* 

Offset 

0x00 la 

*/ 

HANDLE 

hmemClass; 

/* 

Offset 

0x00lc 

*/ 

HINSTANCE 

bins; 

/* 

Offset 

OxOOle 

*/ 

WNDPR0C 

lpfnWndProc; 

/* 

Offset 

0x0020 

*/ 

WORD 

wUnknown2; 

/* 

Offset 

0x0024 

*/ 

WORD 

wl)nknown3; 

/* 

Offset 

0x0026 

*/ 

DWORD 

dwStyle; 

/* 

Offset 

0x0028 

*/ 

DWORD 

dwExStyle; 

/* 

Offset 

0x002c 

*/ 

HMENU 

hmnu; 

/* 

Offset 

0x0030 

*/ 

HANDLE 

hmemTitle; 

/* 

Offset 

0x0032 

*/ 

HANDLE 

hmemScrol1; 

/* 

Offset 

0x0034 

*/ 

HANDLE 

hmemProp; 

/* 

Offset 

0x0036 

*/ 

WORO 

wUnknown5; 

/* 

Offset 

0x0038 

*/ 

WORD 

wUnknown6; 

/* 

Offset 

0x003a 

*/ 

WORO 
) WND; 

rgwUser[l]; 

/* 

Offset 

0x003c 

*/ 


/* End of File */ 

Window Structure for Windows 3.1 


Q l’ve been programming in Windows for about a year 
now and have an interesting question. When an EXE 
automatically loads a DLL, how does Windows know what the 
dependency is? If application A starts up and loads DLL A, then 
application B starts up and begins using DLL A, how does Win¬ 
dows know not to unload DLL A when application A ter¬ 
minates? Does Windows have a Magic Table in the Sky like 
OS/2? I want to create a standard AboutBox that will automat¬ 
ically seek out these links and retrieve a string embedded in 
the DLL (through a standard function in the DLL). Can you help? 

Samuel R. Blackburn 
76300.326@compuserve.com 

A When an application loads a DLL, either implicitly (the 
application is linked to a DLL via its IMPLIB'e d library) or 
explicitly (via LoadLibraryO), Windows increments the refer¬ 
ence count of the DLL being loaded. When the application un¬ 
loads the DLL ( FreeLibraryO) or the application is terminated 
(which causes Windows to unload the DLL), the reference 
count of the DLL is decremented. You can find this count at 
any time using the GetModuleUsagef) function. So when an 
application terminates, Windows checks the reference count 
and, if it has gone to zero, unloads the DLL. 

It is difficult to determine the dependency between DLL 
and application, however. When a module (application or DLL) 
is loaded, it is given a private data segment that is managed 
by KERNEL. This data segment contains a list of linked DLLs 
and their corresponding private data segments. The kernel 
uses this system-wide distributed data to maintain the de¬ 
pendencies. Relying on this undocumented implementation is 
evil at bestl 

With the advent of Windows 3.1, however, comes a useful 
little library called toolhelp. One chunk of its functionality is 
devoted to walking the module list. The routine Module- 
First () begins the walk, then ModuleNextf) examines suc- 


Listing 5 (module.h) 

typedef struct 

( 

/* Size of this structure in bytes. Must be */ 

/* pre-initialized by user. */ 

DWORD dwSize; 

/* Name of the module. */ 

char szModu1e[MAX_MODULE_NAME + 1]; 

/* Module handle. */ 

HANDLE hModule; 

/* Reference count. */ 

WORD wcUsage; 

/* Location of module on disk. */ 
char szExePath[MAX_PATH + 1]; 

/* Reserved for internal use. */ 

WORD wNext; 

) MOOULEENTRY; 

/* End of File */ 

Definition of the MODULEENTRY struct 


cessive modules. The data for each module is stored in a 
MODULEENTRY structure, shown in Listing 5. You could walk the 
list of modules with these functions, using GetProcAddress() 
for each to see if the module contains your standard function. 

Paul Bonneau 
bonneau@hyper.hyper.com □ 
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Displaying Bitmapped 


Microsoft Windows 3.0 provides a rich set of objects and primitives 
for dialog boxes. The basic, predefined control classes are flexible and 
well developed, allowing a great deal of freedom designing a user 
interface. Lacking, however, is a standard mechanism for displaying 
bitmapped images on the client area of a dialog box. 

The icon control class provides the means to display a 32-by-32 
pixel image, so long as the image is stored as an icon. Owing to the 
limited size and the nature of icons, this method does not readily lend 
itself to the display of more general images. Several icons could be 
displayed alongside one another, each displaying a piece of the image, 
like a mosaic. This approach, though workable, entails much effort 
breaking down the source bitmap into 32-by-32 pixel chunks. 

Why Not Use BitBlt? 

Why not just use the Graphics Device Interface (GDI) BitBlt () func¬ 
tion to copy a bitmap to the client area of the dialog box? This is the 
best way to display a bitmap in a dialog box, though doing so is more 
complicated than it first appears. There are several stumbling blocks. 

First, dialog boxes are usually designed with a dialog box editor, 
such as the one supplied with the Windows SDK. These editors usually 
work with dialog box coordinates, which are not based on pixels, but 
on the size of characters in the system font. Horizontally, they are 
expressed in units of one-quarter of the width of an average charac¬ 
ter; vertically, in units of one-eighth of the height of a character. 


anna 


Chris Newbold is currently a junior at the University of Rochester, 
majoring in political science and minoring in journalism. He is the 
author of several Windows 3.0 shareware programs, has experience 
rehosting compilers and source-level debuggers, and is interested in 
systems programming. 
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Images inside Dialog Boxes 


Chris Newbold 


To use Bitblt() to display a bitmap at the proper location 
within the dialog box, the coordinates used by the dialog box 
editor would have to be manually converted to pixels. This 
uncovers a second problem: the coordinates would have to be 
hard-coded, so that any modifications to the dialog box might 
throw off the bitmap placement. 

A method of displaying a bitmap relative to some control 
in the dialog box would be ideal. To see how this might be 
done, it’s necessary to understand how Windows handles 
dialog box controls. 

Understanding Dialog Box Controls 

Each dialog box control, button, icon, check box, combina¬ 
tion box is actually a child window of the dialog box. As child 
windows, they are relatively autonomous with respect to the 
parent dialog box. They have their own window procedures 
which process mouse and keyboard messages just like any 
other window. If another window overlays a control, Windows 
sends a UM_PAINT message directly to the control, instructing 
it to redraw itself. 

Dialog procedures, however, are not real window proce¬ 
dures. For a dialog box, messages are sent directly to DefDlg- 
Proc(), the dialog box analog of DefWindowProc(), not to the 
dialog box procedure. DefDlgProc() first calls the dialog box 
procedure with the message; if the procedure returns TRUE, 
DefDlgProc() exits without taking any further action. If the 
dialog box procedure returns FALSE, however, DefDlgProc() 
performs the default processing for the message. 

This is the reverse of standard window procedures, which 
receive messages first and then pass them on to the Def- 
UindowProcO if they chose not to process them. 

The secret to displaying a bitmap relative to a control 
within a dialog box is to display the bitmap on the client area 
of the control itself. This way, the control can be positioned 
with the dialog editor like any other; the bitmap will always 
display within the control. The choice of control, however, is a 
little tricky. 


□ H 



Choosing the Appropriate Control Class 

There are three likely candidates: a static text control with 
no accompanying text; a solid rectangle-, or a frame. All of 
these controls may be sized arbitrarily and, unlike buttons 
and list boxes, they are static objects, having no functionality. 
Of the three, only the frame control will work properly. 

Child windows are redrawn after their parent window. If 
the dialog procedure intercepts the WM_PAINT message and 
displays an image on the client area of a control, the control 
will redraw its window after it has been altered. Since the 
rectangle controls are solids and since the background behind 
the text in a text control is white, any image drawn on the 
client area of one of these controls will be overwritten when 
the control updates itself. 

The frame control works properly because the area inside 
the bounding box around the control is not altered when the 
control updates. It is merely a frame. 
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Listing 1 

/* bitmap.c */ 
linclude <windows.h> 
linclude "bitmap.h“ 

static HANDLE hlnst; 

BOOL FAR PASCAL AboutDlgProc (HWND hDlg, WORD message, WORD wParam, LONG IParam) 

{ 

HDC hdcFrame, hdcMem; 

HWND hwndFrame; 

HBITMAP hbmpOld, hbmpBitmap; 

RECT rect; 

switch (message) 

{ 

case WM_PAINT: 

hwndFrame = GetDlgltem (hDlg, ID_BLACKFRAME); 
hdcFrame « GetDC (hwndFrame); 

GetClientRect (hwndFrame, Srect); 

hdcMem = CreateCompatibleDC (hdcFrame); 
hbmpBitmap » LoadBitmap (hlnst, szBitmap); 
hbmpOld = SelectObject (hdcMem, hbmpBitmap); 

BitBlt (hdcFrame, 0, 0, rect.right, rect.bottom, hdcMem, 0, 0, SRCCOPY); 
ReleaseDC (hwndFrame, hdcFrame); 

hwndFrame = GetDlgltem (hDlg, ID_GRAYFRAME); 
hdcFrame = GetDC (hwndFrame); 

BitBlt (hdcFrame, 0, 0, rect.right, rect.bottom, hdcMem, 0, 0, SRCCOPY); 
ReleaseDC (hwndFrame, hdcFrame); 

hwndFrame = GetDlgltem (hDlg, ID_WHITEFRAME); 
hdcFrame * GetDC (hwndFrame); 

BitBlt (hdcFrame, 0, 0, rect.right, rect.bottom, hdcMem, 0, 0, SRCCOPY); 
ReleaseDC (hwndFrame, hdcFrame); 

SelectObject (hdcMem, hbmpOld); 

DeleteObject (hbmpBitmap); 

DeleteDC (hdcMem); 
break; 

case WM_COMMAND: 

switch (wParam) 

{ 

case IDOK: 

EndDialog (hDlg, 0); 
return TRUE; 

) 

break; 

} 

return FALSE; 

} 

int PASCAL WinMain (HANDLE hlnstance, HANDLE hPrevInstance, LPSTR 1pszCmdParam, int nCmdShow) 

{ 

HWND hwnd; 

MSG msg; 

WNDCLASS wndclass; 

if (!hPrevInstance) 

( 

wndclass.style = CS_HREDRAW | CSJREDRAW; 

wndclass.lpfnWndProc = WndProc; 

wndclass.cbClsExtra ■ 0; 

wndclass.cbWndExtra = 0; 

wndclass.hlnstance = hlnstance; 

wndclass.hlcon = Loadlcon (hlnstance, szAppIcon); 

wndclass.hCursor » LoadCursor (NULL, IDC_ARR0W); 

wndclass.hbrBackground = GetStockObject (WHITE_BRUSH); 

wndclass.lpszMenuName = NULL; 
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Designing the Dialog Box and the Bitmap 

When designing the dialog box, place a frame control 
where the bitmap should appear. Sizing the control may be 
somewhat difficult if the dialog editor cannot display pixel 
coordinates. It may help to make the bitmap larger than the 
frame control, ensuring that its image will fill the entire area. 
As described below, the image will be clipped at the edge of 
the frame's window. 

The bitmap can be produced using any bitmapped paint 
program, such as SDK Paint or PaintBrush. Be sure to include a 
declaration for the bitmap in the program's resource file. 

Displaying the Image 

To display the bitmap on the client area of the frame con¬ 
trol, the dialog box procedure must process the UM_PAINT 
message. Be sure that the dialog procedure returns FALSE 
after displaying the bitmap, otherwise DefDlgProc() will not 


Listing 2 

case WM_PAINT: 

hwndFrame = GetDlgltem (hDlg, ID_BLACKFRAME); 
hdcFrame = GetDC (hwndFrame); 

GetClientRect (hwndFrame, &rect); 

hdcMem = CreateCompatibleDC (hdcFrame); 
hbmpBitmap = LoadBitmap (hlnst, szBitmap); 
hbmpOld = SelectObject (hdcMem, hbmpBitmap); 

BitBlt (hdcFrame, 1, 1, rect.right - 2, 

rect.bottom - 2, hdcMem, 0, 0, SRCCOPY); 
ReleaseDC (hwndFrame, hdcFrame); 

SelectObject (hdcMem, hbmpOld); 

DeleteObject (hbmpBitmap); 

DeleteDC (hdcMem); 
break; 

/* End of File */ 


bitblt ing within the Frame Rectangle 


Listing 1 — Cont’d 

wndclass.lpszClassName = szAppName; 

RegisterClass (&wndclass); 

} 

hlnst = hlnstance; 

hwnd = CreateWindow (szAppName, szAppName, WS_B0RDER | WS_CAPTI0N | W$_SYSMENU | WS_MINIMIZEBOX, CW_USEDEFAULT, 

CWJJSEDEFAULT, 300, 75, NULL, NULL, hlnstance, NULL); 

ShowWindow (hwnd, SW_SHOWMINIMIZED); 

UpdateWindow (hwnd); 

while (GetMessage (&msg, NULL, 0, 0)) 

( 

TranslateMessage (&msg); 

DispatchMessage (&msg); 

) 

return msg.wParam; 

) 

long FAR PASCAL WndProc (HWND hwnd, WORD message, WORD wParam, LONG IParam) 

{ 

FARPR0C lpfnDlgProc; 

HMENU hMenu; 

switch (message) 

( 

case WM_CREATE: 

hMenu = GetSystemMenu (hwnd, FALSE); 

AppendMenu (hMenu, MF_SEPARAT0R, 0, NULL); 

AppendMenu (hMenu, MF_STRING, IDM_AB0UT, szSysAbout); 
return 0; 

case WM_SYSC0MMAND: 

switch (wParam) 

( 

case IDM_AB0UT: 

lpfnDlgProc = MakeProcInstance (AboutDlgProc, hlnst); 

DialogBox (hlnst, szAppAbout, hwnd, lpfnDlgProc); 

FreeProcInstance (lpfnDlgProc); 
return 0; 

) 

break; 

case WM_DESTR0Y: 

PostQuitMessage (0); 
return 0; 

default: 

return DefWindowProc (hwnd, message, wParam, IParam); 

} 

return DefWindowProc (hwnd, message, wParam, IParam); 

) 

/* End of File */ 
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Listing 3 

case WM_PAINT: 

hwndFrame = GetDlgltem (hDlg, ID_BLACKFRAHE); 
hdcFrame = GetDC (hwndFrame); 

GetClientRect (hwndFrame, &rect); 

hdcMem = CreateCompatibleDC (hdcFrame); 
hbmpBitmap = LoadBitmap (hlnst, szBitmap); 
hbmpOld = SelectObject (hdcMem, hbmpBitmap); 

InvalidateRect (hwndFrame, NULL, FALSE); 

BitBlt (hdcFrame, 0, 0, rect.right, 

rect.bottom, hdcMem, 0, 0, SRCCOPY); 
ReleaseDC (hwndFrame, hdcFrame); 

SelectObject (hdcMem, hbmpOld); 

DeleteObject (hbmpBitmap); 

DeleteDC (hdcMem); 
break; 

/* End of File */ 

Using InvalidateRect() to Update Frame 


process the message and the remainder of the dialog box will 
not be redrawn. Listing 1 shows a skeleton program which 
displays an "About" dialog box with three bitmap images. The 
three images illustrate the three frame types: black, gray, and 
white. Listings of the header, resource, dialog and module 
definition files appear following the program. 

When it receives a WM_PAINT message, the dialog box pro¬ 
cedure first obtains the window handle of the frame control 
with GetDlgItem(). Next, the dialog procedure calls Get- 


Listing 4 (bitmap.h) 

/* bitmap.h */ 

BOOL FAR PASCAL AboutOlgProc (HWND, WORD, WORD, LONG); 
int PASCAL WinMain (HANDLE, HANDLE, LPSTR, int); 
long FAR PASCAL WndProc (HWND, WORD, WORD, LONG); 

static char szAppIconf] * "icnAppIcon 11 ; 
static char szAppAboutf] ■ "dlgAppAbout"; 
static char szSysAbout[] « “About..."; 
static char szBitmap[] = "bmpAppBitmap"; 
static char szAppNamef] = “Bitmaps"; 

#define IDM_AB0UT 100 

Idefine ID_BLACKFRAME 101 
Idefine ID_GRAYFRAME 102 
Idefine ID_WHITEFRAME 103) 

/* End of File */ 


ClientRect() and GetDC ()with the window handle of the 
frame control. These calls retrieve, respectively, the dimen¬ 
sions of the frame’s client area and a display context (DC) for 
this area. 

Before it can display the bitmap, the dialog procedure must 
load the bitmap from the program executable into memory. It 
creates a memory display context compatible with th^t of the 
frame control by calling CreateCompatibleDC(). This produces 
a display context in memory with the same hardware at¬ 
tributes as the context for the frame control's client area. The 
bitmap is loaded from the executable with LoadBitmap() and 
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Listing 5 

/* bitmap.rc */ 

#include <windows.h> 

#include "bitmap.h" 

icnAppIcon ICON bitmap.ico 
bmpAppBitmap BITMAP bitmap.bmp 

rcinclude bitmap.dig 

bitmap.dig 

dlgAppAbout DIALOG 42, 42, 236, 100 

STYLE DS_M00ALFRAME | WS_P0PUP | WS_VISIBLE | WS_CAPTI0N 
CAPTION "Bitmaps" 

FONT 8, "Helv" 

BEGIN 

CONTROL "", ID_BLACKFRAME, "Static", SSJLACKRECT, 6, 6, 70, 70 

CONTROL "", ID_GRAYFRAME, "Static", SS GRAYRECT, 82, 6, 70. 70 

CONTROL "“, ID_WHITEFRAME, "Static", SS_WHITERECT, 158, 6, 70, 70 

DEFPUSHBUTTON "Ok". TdOK, 94, 80, 40, 16 
END 

Resource Compiler File 


Listing 6 

bitmap.def 
NAME Bitmaps 

DESCRIPTION 'Copyright (C) 1991 by Chris Newbold. Version 1.0.' 
EXETYPE WINDOWS 
STUB 'WINSTUB.EXE' 

CODE PRELOAD MOVABLE DISCARDABLE 

DATA PRELOAD MOVABLE MULTIPLE 

HEAPSIZE 1024 

STACKSIZE 8192 

EXPORTS WndProc 

AboutDlgProc 

/* End of File */ 


There are two ways to avoid this 
visual fumble. The most straightforward 
is simply to bitblt the image within the 
frame control's border by using (1,1) as 
the coordinate for the upper-left corner. 
Subtract two from each dimension of 
the size of the frame’s client area and 
use these values for the extent of the 
bitblt. The code fragment in Listing 2 il¬ 
lustrates this approach. 

The second method is to force the 
frame control to update its entire client 
area. The dialog procedure invalidates 
the entire client area of the frame con¬ 
trol by calling InvalidateRectf ), with 
a NULL pointer for the update region. 

Since the UM_PAINT message sent to 
the frame control will not be processed 
until the dialog procedure finishes with 
its UM_PAINT message, the entire frame 
will be redrawn after the bitblt. Listing 3 
illustrates this technique. 

Displaying a bitmapped image within 
a dialog box requires more effort than 
displaying the same image in a regular 
GDI window. With a little care, however, 
the method presented here provides a 
clean way to spruce up any dialog box. □ 


selected into the memory display context with Select- 
Object (). Note that the handle of the original bitmap in the 
context is saved; it must be restored before the context is 
destroyed. 

At this point, everything is set to BitBlt() the image from 
the memory context onto the client area of the frame control. 
The dimensions of the frame window, obtained earlier by the 
call to GetClientRect(), provide the extent to use when call¬ 
ing BitBlt(). This ensures that the image is clipped at the 
edge of the frame, even if the bitmap is larger than the 
control's client area. 

The Intelligent Redraw Pitfall 

There is one more consideration, however. When another 
window overlays the dialog box, Windows sends the dialog 
procedure a UM_PAINT message, through DefDlgProc(), to 
repaint the mangled part of its client area. UM_PAINT messages 
are also sent to any affected controls. Once DefDlgProcf) 
returns from its WM_PAINT, the controls begin processing their 
messages. 

Windows is smart about how the controls are repainted. If 
only half of the control needs updating, only that half is 
repainted. This significantly increases display speed, bitblting 
the image onto the client area of the frame control overwrites 
all of the control’s client area. This region is not automatically 
added to the update region for the control, however. So, 
when the frame control repaints its border, only the part 
overwritten by the other window gets redrawn. The rest of 
the box, overlaid by the BitBltf), is no longer visible. 
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For a Consistent 
User Interface, 

Center Your Windows 

William Smith 


Introduction 

Consistency is the key to designing a user interface with a profes¬ 
sional appearance. Under Windows, the practice of centering dialog 
boxes and windows in the application's main window or the Windows 
desktop (display screen) gives programs a consistent and polished look. 
The existing Windows programs that adhere to this convention are more 
intuitive and easy to use; those that do not tend to feel somewhat 
awkward (having to chase dialog boxes around the screen is not a 
favorite video game). If you consistently display dialog boxes in the 
same location, the user always knows where to look and where to 
move the mouse - even before the dialog box is displayed. 

The technique of centering windows and dialog boxes within their 
respective parent windows or within the desktop is simple and 
straightforward. This article details how it is done and presents two 
easy-to-use functions that you can add to your library. The amount of 
code and overhead required to accomplish this is small and the gains 
are worth it. The code is in C and has been tested under both Borland 
C++ and Microsoft C with the Windows 3.0 SDK. It will work with any 
memory model. 

Centering How-To 

The goal is to center a dialog box or subordinate window inside its 
parent window. I will refer to the subordinate window as the center 
window and the windows within which the centering is to occur as the 
parent window. 

Centering must perform two tasks: (1) calculate the centered location; 
(2) move the window to the centered location. 


William Smich is the Engineering Manager at Montana Software, a software 
development company specializing in custom Windows applications. 
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The algorithm takes the difference between the parent 
window size and the center window size. The algorithm then 
halves this difference and adds it to the value of parent 
window's location. I use this method to calculate both the X 
and Y location values, that is, the values that represent the 
center window’s centered location. A window location is the 
window’s top left corner position in screen coordinates. Screen 
coordinates are measured in pixels starting from the top left 


corner of the display as 0,0 and increasing going down and to 
the right. Once the centered location is known, the process 
can then move the center window to the centered location. 

Listing 1 presents the code for the two functions used in 
the window centering process, CenterWindowRect () and 
CenterWindow(). Listing 2 contains the associated #include file 
for the functions. These functions are used both to calculate 
where to move the window and to actually move the window. 


Listing 1 (cntr_wnd.c) 

/***************************************************** 

points to are assumed to be the valid 

File Name: CNTR WND.C 

current values for the center window. 

Expanded Name: Center Window 

They are used to calculate the height and 

Description: Library of functions for 

width of the center window. 

centering windows. 

***************************************************** j 

Program List: 

void CenterWindowRect( HWND hWndParent, 

Global Function List: CenterWindow 

HWND hWndCenter, LPRECT RectCenter ) 

CenterWindowRect 

( 

Static Function List: 


Local Macro List: BYTE ALIGN 

RECT RectParent; 

Global Data: 

int CenterX, CenterY, Height, Width; 

Static Data: 


Portability: MS Windows, Any memory model. 

if ( hWndParent ** NULL ) 

Any windows compatable C Compiler 

{ 

******************************************************/ 

hWndParent = GetDesktopWindowQ; 

i 

/* MS Window */ 


linclude <windows.h> 

GetWindowRect( hWndParent, &RectParent ); 

/* Own */ 

if ( hWndCenter != NULL ) 

linclude <cntr wnd.h> 

i 


GetWindowRect( hWndCenter, RectCenter ); 

Idefine BYTE_ALIGN( x) ( (x + 4) & ~7) 

) 

j ***************************************************** 

Width * ( RectCenter->right - RectCenter->left ); 

Name: CenterWindow 

Height = ( RectCenter->bottom - RectCenter->top ); 

Parameters: hWndParent - handle of parent window 

CenterX = (( RectParent.right - RectParent.left ) 

hWndCenter - handle of window to center 

- Width ) / 2; 

bRepaint - Flag to specify repainting 

CenterY = (( RectParent.bottom - RectParent.top ) 

after moving. If bRepaint 

- Height ) / 2; 

is 0, the window is not 


repainted. 

if (( CenterX < 0 ) || ( CenterY < 0 )) 

Return: 

( 

Description: Moves a window to the center of the 


specified parent window. If parent 

/* The Center Window is smaller than the 

window is NULL, the desktop window is 

** parent window. */ 

used. Optionaly sends a WM PAINT message 


if bRepaint is non-zero. 

if ( hWndParent != GetDesktopWindowQ ) 

*****************************************************/ 

{ 

void CenterWindow( HWND hWndParent, HWND hWndCenter, 

/* If the parent window is not the 

BOOL bRepaint ) 

** desktop use the desktop size. */ 

( 

CenterX = ( GetSystemMetrics( $M CXSCREEN ) 

RECT RectCenter; 

- Width ) / 2; 

CenterY ■= ( GetSystemMetrics( SM CYSCREEN ) 

CenterWindowRect( hWndParent, hWndCenter, 

- Height ) / 2; 

) 

ARectCenter ); 


MoveWindowf hWndCenter, RectCenter.left, 

CenterX = ( CenterX < 0 ) ? 0: CenterX; 

CenterY = ( CenterY < 0 ) ? 0: CenterY; 

RectCenter.top. 


( RectCenter.right - RectCenter.left ), 

} /* if CenterX */ 

( RectCenter.bottom - RectCenter.top ), 

else 

bRepaint ); 

( 

) /* funtion CenterWindow */ 

CenterX += RectParent.left; 

CenterY += RectParent.top; 

} 

j ***************************************************** 

/* Byte Align in the x direction for speed. */ 

Name: CenterWindowRect 

CenterX - BYTE ALIGN( CenterX ); 

Parameters: hWndParent - handle of parent window 


hWndCenter - handle of parent window 

/* Copy the values into RectCenter. */ 

RectCenter - pointer to RECT struct 

RectCenter->left * CenterX; 

Return: Indirectly returns the values of the 

RectCenter->right ■ CenterX + Width; 

calculated center postion in RectCenter 

RectCenter->top = CenterY; 

Description: Gets the X and Y location in screen 

RectCenter->bottom - CenterY + Height; 

coordinates of the window to center. If 


the center window handle is NULL, the 

} /* funtion CenterWindowRect */ 

values in the RECT struct that RectCenter 

/* End of File */ 
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CenterWindowRect() calculates the centered rectangular 
screen coordinates of the center window, then stuffs these 
values into the RECT structure pointed to by the parameter 
RectCenter. CenterUindowRectf) uses the Windows function 
GetUindowRect() to get the rectangular coordinates of the 
parent window and the center window. If the parent window 
handle is NULL, CenterUindowRect() gets the handle to the 
desktop window with a call to the Windows function Get- 
DesktopUindow(). Under these circumstances, CenterUindow- 
Rect() uses the desktop window as the parent window. If the 
center window handle is NULL, CenterUindowRect() assumes 
that the structure pointed to by RectCenter already contains 
the center window coordinates. This feature is handy if you 
want to calculate the center coordinates of a window before 
you create it. It can also be used to generate the rectangular 
coordinates of any rectangle that is to be centered in a win¬ 
dow. 

CenterUindowRect() also checks to see if the center win¬ 
dow is larger than the parent window. When this is the case, 
CenterUindowRect() forces the parent window to be the 
desktop. What happens when the center window is larger 
than the desktop? In this case, CenterUindowRect() sets the 
center location to 0,0. CenterUindowRectf) uses the macro 
BYTE_ALIGN() to ensure that the X location is byte aligned. 
Byte alignment of windows helps speed up redraws when the 
window is moved. 

CenterUindow() uses the coordinates calculated by 
CenterUindowRectf) to move the window with a call to 
MoveMindow(). Besides the window handle, location, and size, 
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Listing 2 (cntr_wnd.h) 

I ***************************************************** 

File Name: CNTR_WND.H 
Expanded Name: Center Window 
Description: Include file for CNTR_WND.C 

*****************************************************j 

#if !defined( CNTR_WND_DEFINED ) 

fdefine CNTR_WND_DEFINED 

void CenterWindow( HWND hWndParent, 

HWND hWndCenter, BOOL bRepaint ); 

void CenterWindowRect( HWND hWndParent, 

HWND hWndCenter, LPRECT RectCenter ); 

fendif 

/* End of File */ 

MoveUindow() also requires a flag to indicate whether the 
window, once it is moved, is to be repainted. The flag is also a 
parameter to CenterUindow() and is passed on through to 
MoveWindow(). When you center a window upon its creation, 
you can set this flag to 0. Upon window creation, Windows 
will take care of sending a WM_PAINT message. When you call 
CenterUindow() for a window that already is displayed, you 
may have to set this flag to a non-zero value to generate a 
UM_PAINT message. 

Centering Windows 

There are two methods for centering a window. The first is 
to specify the correct location and size when calling Create- 
Uindow(). To do this, you must know the size of the window 
before you create it. To get the location, use the Center- 
UindowRect() function with the RECT structure pointed to by 
RectCenter containing the appropriate values of RectCenter- 
>left, RectCenter->right, RectCenter->top, RectCenter- 
>bottom. You must make sure that (RectCenter->bottom - 
RectCenter->top) is equal to the desired height and (Rect- 
Center->right - RectCenter->left) is equal to the desired 
width. The center window handle passed to CenterUindow- 
Rect() must be NULL in order to force CenterWindowRect() 
to use the values in the RECT structure. CenterUindowRect() 
modifies RectCenter with the calculated values of the 
centered position. Use these values as parameters in Create- 
Uindowf). The following code fragment illustrates this techni¬ 
que. 

RECT RectCenter; 

RectCenter.left = 0; 

RectCenter.right = KnownWidth; 

RectCenter.top = 0; 

RectCenter.bottom = KnownHeight; 

CenterWindowRect( hWndParent, NULL, 

&RectCenter ); 

hWnd = CreateWindow( 

"WindowClassName", 

"Window Caption", 

WS_0VERLAPPEDWIND0W | 

WS_VISIBLE | 

WSJSCROLL | 

WS_HSCR0LL, 
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Listing 3 (c_w_demo.c) 


File Name: 
Expanded Name: 
Description: 
Program List: 
Global Function List: 
Static Function List: 
Local Macro List: 
Global Data: 
Static Data: 
Portability: 


C_WJEM0.C 

Center Window Demo 

Center Window Demo Program 

C_W_DEM0.C CNTR_WND.C 

CenterWindow 

CenterWindowDi al og 


_hlnstance _hWnd 

MS Windows, Any memory model. 

Any windows compatable C Compiler 

r********************************/ 


★★★★A*************************************************/ 


/* MS Windows */ 
linclude <windows.h> 


if ( _hWnd -- NULL ) 

( 

/* If window could not be created, return. */ 
MessageBeep( 0 ); 
return ( FALSE ); 

) 

ShowWindow( _hWnd, nCmdShow ); 

UpdateWindowI _hWnd ); 

while ( GetMessagef iMessage, NULL, NULL, NULL ) ) 

( 

TranslateMessage( iMessage ); 

DispatchMessage( iMessage ); 

) 


/* Types and Prototypes */ 
linclude <cntr_wnd.h> 

/* Own */ 

linclude <c w demo.h> 


return ( (int)Message.wParam ); 
} /* function WinMain */ 


/* Prototypes of functions called only by windows. */ 
LONG FAR PASCAL CenterWindowDemoProc( 

HWND hWnd, WORD iMessage, WORD wParam, 

LONG 1 Param ); 

BOOL FAR PASCAL CenterWindowDialogProc( 

HWND hDlg, WORD iMessage, WORD wParam, 

LONG 1Param ); 

/* static data */ 
static HWND _hWnd; 
static HANDLE _hlnstance; 

J ***************************************************** 

Name: WinMain 

Description: Program entry point. 

***************************************************** j 

int PASCAL WinMain( HANDLE hlnstance, 

HANDLE hPrevInstance, LPSTR 1pszCmdParam, 
int nCmdShow ) 

I 

MSG Message; 

WNDCLASS WndClass; 

char ‘CenterWindowDemoName = "CenterWindowDemo"; 

_hlnstance = hlnstance; 

if ( IhPrevInstance ) 

( 

WndClass.style = CS_HREDRAW | CSJREDRAW; 
WndClass.lpfnWndProc = CenterWindowDemoProc; 
WndClass.cbClsExtra = 0; 

WndClass.cbWndExtra = 0; 

WndClass.hlnstance » _hlnstance; 

WndClass.hlcon • LoadIcon( _hlnstance, 

CenterWindowDemoName ); 

WndClass.hCursor ■ 

LoadCursorf NULL, IDC_ARR0W ); 

WndClass.hbrBackground * C0L0R_WIND0W + 1; 
WndClass.lpszMenuName = 

CenterWindowDemoName; 

WndClass.IpszClassName ■ 

CenterWindowDemoName; 

if ( RegisterClass( iWndClass ) =- FALSE ) 

{ 

MessageBeep( 0 ); 
return ( FALSE ); 

) 

) 

/* Create the window with default pos. and size */ 
hWnd • CreateWindowf CenterWindowDemoName, 

“Center Window Demo", 

WS_OVERLAPPEDWINDOW j WS VISIBLE | 

WSJSCROLL | WS HSCROLL, - 
CW USEDEFAULT, CW_USEDEFAULT, 

CW'USEDEFAULT, CW USEDEFAULT, 

NULL, NULL, _hlnstance, NULL ); 


J***************************************************** 

Name: CenterWindowDemoProc 

Description: Window Procedure for center window demo 
program. This is called by Windows only. 

***************************************************** j 

long FAR PASCAL CenterWindowDemoProc( HWND hWnd, 

WORD iMessage, WORD wParam, LONG 1Param ) 

( 

switch ( iMessage ) 

( 

case WM CREATE: 

( 

CenterWindow{ NULL, hWnd, FALSE ); 
break; 

( 
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Listing 3 — Cont’d 


case WM_COMMAND: 

{ 

switch ( wParam ) 

{ 

case IDM_CENTER_MAIN: 

{ 

CenterWindow( NULL, hWnd, 

TRUE ); 

break; 

} 

case IDMJ3IAL0G: 

{ 

FARPROC lpfCenterWindowDialog; 


break; 

} 

case WM_DESTROY: 

{ 

PostQuitMessage( 0 ); 
break; 

) 

default: 

{ 

return ( DefWindowProc( hWnd, iMessage, 
wParam, IParam ) ); 

} 

) /* switch iMessage */ 


lpfCenterWindowDialog = 
MakeProcInstance( 
CenterWindowDialogProc, 
_hlnstance ); 

DialogBox( _hlnstance, 

“CenterWindowDialog", 
hWnd, 

lpfCenterWindowDialog ); 
FreeProcInstance( 

lpfCenterWindowDialog ); 

break; 

} 

case IDM_EXIT: 

{ 

SendMessage( hWnd, 

WMCLOSE, 0, OL ); 

break; 

) 

default: 

{ 

break; 

} 
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return ( FALSE ); 

) /* function CenterWindowDemoProc */ 


y***************************************************** 
Name: CenterWindow 

Description: Dialog Procedure for center window demo. 

Processes commands to center the dialog 
box within the parent window or within 
the desktop. This function is called 
by Windows only. 

*****************************************************j 

BOOL FAR PASCAL CenterWindowDialogProc( HWND hDlg, 

WORD Message, WORD wParam, LONG IParam ) 


switch ( Message ) 

{ 

case WMJNITDIALOG: 

{ 

CenterWindow( _hWnd, hDlg, FALSE ); 
return ( TRUE ); 

} 

case WM COMMANO: 

{ 

switch ( wParam ) 

1 

default: 

{ 

break; 

} 

case IDCANCEL: 
case IDOK: 

1 

EndDialogf hDlg, FALSE ); 
return ( TRUE ); 

1 

case IDD_PARENT: 

{ 

CenterWindow( _hWnd, hDlg, 
TRUE ); “ 

break; 

1 

case IDD_DESKTOP: 

1 

CenterWindowf NULL, hDlg, 

TRUE ); 

break; 

} 

} /* switch wParam */ 

break; 

} 

default: 

1 

break; 

1 

) /* switch message */ 

return ( FALSE ); 

} /* function CenterWindowDialogProc */ 

/* End of File */ 


June 1992 






















Listing 4 (c_w_demo.h) 


File Name: C_W_DEMO.H 
Expanded Name: Center Window Demo 
Description: Include file for C_W_DEM0.C 

★ ★if************************************************** j 

#define IDM_CENTER_MAIN 100 
Idefine IDM_DIALOG 101 
Idefine IDM_EXIT 102 

Idefine IDD_PARENT 200 
Idefine IDD DESKTOP 201 


/* End of File */ 


Listing 5 (c_w_demo.rc) 


linclude <windows.h> 
linclude <c_w_demo.h> 

CenterWindowDemo MENU 

{ 

POPUP "&Demo" 

{ 

MENUITEM "SCenter Main", IDM_CENTER_MAIN 
MENUITEM "&Dialog.IDM_DIALOG 
MENUITEM SEPARATOR 
MENUITEM "E&xit", IDM_EXIT 
} 

} 

CenterWindowDialog DIALOG LOADONCALL MOVEABLE 
DISCARDABLE 20, 52, 136, 140 
STYLE WS_B0RDER | WS_CAPTION | WS_DLGFRAME | 
WS_SYSMENU | DS_M0DALFRAME | WS_P0PUP 
CAPTION "Center Window / Dialog Demo" 

BEGIN 

CONTROL "Center Window Demo", -1, "static", 
SS_CENTER | WS_CHILD, 8, 12, 120, 8 

CONTROL "Demonstrates Centering", -1, "static", 
SS_CENTER | WS_CHILD, 8, 28, 120, 8 

CONTROL “Dialog Boxes", -1, "static", SS_CENTER | 
WS_CHILD, 8, 36, 120, 8 

CONTROL “* -1, "STATIC", WS_CHILD | WSVISIBLE | 
0x4L, 0, 46, 136, 2 

CONTROL "Center Within the Parent Window", 111, 
"static", SS_CENTER | WS_CHILD, 8, 52, 

120, 8 

CONTROL "or", -1, "static", SS_CENTER | WS_CHILD, 
8, 60, 120, 8 

CONTROL "Center Within the Desktop", -1, 

"static", SS_CENTER | WS_CHILD, 8, 68, 

120 , 8 

CONTROL "CENTERWINDOWDEMO", -1, "static", 

SS ICON | WS_CHILD, 4, 4, 32, 32 

CONTROL "&Parent", IDD_PARENT, "button", 
BS_PUSHBUTTON | WS_TABSTOP | WS_CHILD, 

48, 80, 40, 16 

CONTROL “SDesktop", IDD_DESKTOP, “button", 
BS_PUSHBUTTON | WS_TABSTOP | WS_CHILD, 

48, 100, 40, 16 

CONTROL "SClose", 1, “button", BS_DEFPUSHBUTTON | 
WS_TABSTOP j WS_CHILD, 48, 120, 40, 16 
END 
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RectCenter.left, RectCenter.top, 

RectCenter.right - RectCenter.left, 

RectCenter.bottom - RectCenter.top, 

NULL, NULL, hlnstance, NULL ); 

The second method involves reacting to the UM_CREATE mes¬ 
sage in the window procedure. Windows sends this message 
to your window procedure right before displaying the window. 
Just make a call to CenterUindow() when processing the 
UM_CREATE message. You must use this technique if you call 
CreateUindow() with the size and location parameters set to 
CWJSEDEFAULT. 

Example 

Listing 3 contains a demonstration program that illustrates 
this technique. There are three functions in the demonstration 
program: UinMain(), CenterUindowDemoProc() and Center- 
WindowDialogProcf). Listing 4 contains the associated Hn- 
clude file for the demonstration program. 

In the demo program, whenever the window procedure, 
CenterUindowDemoProc (), receives a UM_CREATE message, the 
window procedure calls CenterUindow(). Since this is the 
application’s main window and there is no parent window, 
CenterUindow() will center the window on the desktop. 

When the demo program starts, the main window is 
centered on the screen. There is a menu choice, Center Main, 
under the pull-down Demo menu-, invoking this menu choice 
recenters the main window. The program does this by calling 
CenterWindow() from within CenterUindowDemoProc() in 
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response to the WM_COMMAND message when the value of w- 
Param is equal to IDM_CENTER_MAIN. If you invoke this menu 
choice after resizing or moving the main window, you will see 
the main window recentered on the screen. 

Centering Dialog Boxes 

Centering dialog boxes upon creation requires responding to 
the UM_INITDIALOG message from within the dialog procedure. 
Windows sends this message to your dialog procedure right 
before displaying the dialog box. The demonstration program, 
Listing 3, contains a dialog procedure, CenterUindowDialog- 
Proc(), that calls CenterMindow() when processing the 
WM_INITDIALOG message. CenterWindowDialogProc() also 
calls CenterWindow() when processing the UM_COMMAND mes¬ 
sage and the IDD_PARENT and IDD_DESKTOP button pushes. 
Pressing the Parent button in the dialog box will center the 
dialog box inside the parent window. Pressing the Desktop 
button centers the dialog box within the desktop. 

I encourage you to experiment with the demo by resizing 
and moving the main window, then invoking the dialog box 
through the Demo - Dialog menu choice. Remember that if 
the main window is smaller than the dialog box, the dialog 
box will be centered within the desktop: this is the case even 
if you select the Parent pushbutton. You can also manually 
move the dialog box off center and then recenter it. 

If you want to allow users to move dialog boxes manually, 
you must create the boxes with a caption and system menu. 
This is generally a good practice to follow in creating dialog 
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Listing 6 (c_w_demo.def) 

NAME CENTERWINDOWDEMO 

DESCRIPTION 'CENTERWINDOWDEMO Listing 6' 

EXETYPE WINDOWS 
STUB 'WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 
STACKSIZE 8192 

EXPORTS CenterWindowDemoProc @1 
CenterWindowDialogProc @2 


Listing 7 (c_w_demo. mak) 

all: c_w_demo.exe 

c_ w _d emo.o bj: c_w_d emo. c 

cl /ASw /c /Gsw /W3 /Zp /nologo $*.c 

cntr_wnd.obj: cntr_wnd.c 

cl /ASw /c /Gsw /W3 /Zp /nologo $*.c 

c_ w _d em °.res : c_w_demo.rc 
rc -r c_w_demo.rc 

c _w_de m o. exe: c_w_demo.obj \ 
cntr_wnd.obj \ 
c_w_demo.def \ 
c w_demo.res 

link /A:16 /BA /NOD /NOE /NOL /nologo @« 
c_w_de m o+ 
cntr_wnd 
c _ w _ demo ■ exe 

11 ibcew 1ibw 
c_ w _d e mo.def 
« 

rc c w demo.rc c w demo.exe 


boxes, since it lets the user uncover what is underneath a 
dialog box. To provide for movable dialog boxes, include the 
WS_CAPTION and WSJYSMENU in the STYLE control area of the 
dialog resource script. See Listing 5 for an example of a 
resource script that defines a movable dialog box. 

Additional Listings 

Listing 5 contains the windows resource script file for the 
demo program. The resource file defines the main window 
menu and the dialog box. Listing 6 contains the linker defini¬ 
tion file. Listing 7 contains a make file for Microsoft C. The only 
other file required to build the demo program is the icon file, 
which is a binary file and cannot be printed (it is included on 
the code disk). You can compile and link the code without 
changes for any memory model with either the Microsoft C or 
Borland C++ compiler. 

Wrap Up 

The rapid development of de facto standards for ease of 
use in user interfaces means that more and more is 
demanded of programmers as they try to keep up with user 
expectations. The CenterUindouf) and CenterUindowRectf) 
can help programmers create consistent and predictable be¬ 
havior in their Windows programs. □ 
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Soft-ICE/W from Nu-Mega Technologies 

Daniel Norton 


Introduction 

Most developers who program in C under Windows are 
very familiar with Microsoft's CodeView for Windows but are 
unaware of either the existence or the benefits of lower-level 
debuggers. In fact, the Windows SDK includes a lower-level 
debugger, WDEB386, but relatively few developers know 
about it and even fewer know how to use it. I suspect the 
reason is that most programmers would find it clumsy to use, 
especially by comparison with the full-screen source code 
debugging offered by CodeView. 

Nu-Mega Technologies' newest debugger, Soft-ICE/W, offers 
both full-screen and low-level debugging. The advantage of 
full-screen over line-oriented debugging is well recognized 
(compare CodeView and SYMDEB, for instance), but the useful¬ 
ness of a debugger that is lower-level than CodeView is per¬ 
haps not immediately obvious. 

Although Soft-ICE/W compares closely to CodeView for typi¬ 
cal Windows applications and DLLs, its strength really lies in 
debugging unconventional applications - such as those that 
use the DOS Protected Mode Interface (DPMI) to interface Win¬ 
dows applications with DOS applications - and DLLs that serve 
as device drivers. In particular, Soft-ICE/W is a must for debug¬ 
ging Windows virtual device drivers (VxDS) - CodeView cannot 
help at all with these. 

Debugging Windows Applications 

For typical Windows applications, Soft-ICE/W offers 
functionality similar to CodeView's, but it provides a few extra 
features that might make you select it over CodeView. 

For example, Soft-ICE/W can run from a remotely attached 
terminal. Although CodeView can run on the main display, the 
screen-swapping that goes on when CodeView flips from the 


Windows display to the CodeView display can become annoy¬ 
ing. If you are fortunate enough to have a separate 
monochrome adapter on your system, you don't have this 
problem. Flowever, if you have an IBM PS/2, the expense of a 
second display adapter and monitor can be prohibitive. 

Soft-ICE/W solves the problem by using a COM port to con¬ 
nect to a second PC that acts as the debugging console. To set 
the communication up, you run a null-modem cable between 
the two PCs and invoke a special program (provided with Soft- 
ICE/W) that connects to the target system. Where a speed of 
19,200 bps satisfies most requirements, Soft-ICE/W will actually 
run the line at up to 115,000 bps, making any delay imposed 
by transferring the data over a serial line negligible. 

This strategy not only keeps the debugging output 
separate from the main Windows display, but also allows for a 
separate keyboard. If your Windows application processes 
keyboard messages such as WM_KEYD0UN and WM_SYSKEYDOWN, 
this feature of Soft-ICE/W becomes a necessity. 


Product Information 

■ Product: SoftICE/W 

■ Price: $386 

order directly from: 

Nu-Mega Technologies 
P.O. BOX 7780 
Nashua, NH 03060-7780 
voice: 603-889-2386 
FAX: 603-889-1135 


Daniel Norton is the author of the new book, Writing Windows Device Drivers, from Addison-Wesley publishers. He has been 
developing microcomputer software since before the introduction of the IBM PC. He helped develop the device driver architecture 
for the 32-bit version of OS/2 for Microsoft and is now principal consultant for Cherry Hill Software, a development consulting firm 
in the Philadelphia metropolitan area. 
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0) Message *129F:000014B4 0024 

-byte-PROT- — 
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0030:00000010 F4 06 70 00 54 FF 00 F0-CC 93 00 F0 D0 IB 00 F0 ..p.T . 

-gener ic. c-PR0T16— 

08216:WORD uParam; /** additional inforMation 

00217:LONG lParan: /*» additional inforMation 

00218:< 

00219: FARPROC lpProcAbout; pointer to the "About" function 

00220 : 

00222: case Uf1_C0f1MAND: /** Message: com wand from application Menu **/ 

00223: if (uParaM == IDM_ABOUT) < 

00224: lpProcAbout = MakeProcInstance(About« hlnst): 

00225: 


color 70 70 17 30 70 
color 70 7b 17 30 70 


Enter A Command Or ? For Help 

_ Sample SoftICE/W Screen _ 

For example, if you have tried to step through code that 


processes such messages, or if you have tried to press Ctrl- 
Alt-SysRQ to enter CodeView, you have probably run into the 
situation where the Ctrl and Alt keys are reported to the 
Windows application as having been pressed, but never 
released. In fact, the keys are released when CodeView be¬ 
came active, but because this occurs outside the scope of nor¬ 
mal Windows processing, the event is not noted. When the 
debugging terminal and keyboard are separate, this kind of 
problem cannot occur. 

If you use one of the new 32-bit compilers that works with 
Windows (such as watcom C), you’ll find Soft-ICE/W particular¬ 
ly helpful, since the debugger’s register window shows all 32 
bits of the CPU’s registers. Unfortunately, since most Windows 
applications are still only 16-bit and the upper 16 bits of the 
32-bit registers can’t be hidden, this feature may prove an 
annoyance to some programmers. 

To actually debug a Windows application, you run a small 
application named WLDR that loads the symbols into the 
debugger (which is loaded when Windows starts). WLDR 
presents a dialog box into which you enter the name of the 
application to be debugged. I looked for but could not find a way 
to bypass the dialog box and specify the name automatically. 

Poking Around in the Windows Kernel 

I have not “hacked” around inside an operating system in 
quite a while (since I worked on OS/2 internals, actually), and 
using Soft-ICE/W reminded me of how much I enjoy it. Soft¬ 
ICE/W makes it easy and fun to poke around inside Windows 
at every level. Without specifying even a single symbol file, I am 
able to set breakpoints within Windows at some of the more 
mundane (to me) entry points, such as OpenFile(), and some of 
the more esoteric ones, such as PrestoChangoSelector(). 

Windows 386 enhanced mode actually consists of a Virtual 
Machine Manager (VMM) which manages multiple DOS sessions 
(one of which is Windows). Soft-ICE/W lets me set breakpoints 
and lets me disassemble code there, too. If you have the 
Device Development Kit (DDK) or my book, Writing Windows 
Device Drivers, you might recognize such VMM services as 
Get_Last_Updated_System_Time() and Get_Sys_VM_Handle(). 


With Soft-ICE/W it’s easy to see that 
these two functions simply load a 32- 
bit value into a register and return. If 
you are a low-level bit-twiddler (as I 
am) and you want to see something a 
little more complicated, step through 
Resume_Exec() to see how Windows 
switches among VMM code, Windows 
kernel code, and DOS code. 

In addition to having access to 
symbols to exported labels, Soft-ICE/W 
provides commands that let you ex¬ 
plore the task- and memory-manage¬ 
ment structures within Windows. The 
MOD command displays a list of all of 
the modules currently loaded, includ¬ 
ing all programs, DLLs, and fonts. The 
TASK command lists active tasks, along 
with a description of their stacks and 
their module handles. 

Getting one level lower, into 
memory management, the HEAP command dumps the system 
heap, in much the same fashion as the SDK HEAPWALKER utility. 
To see the global handles assigned to a task, you specify the 
task name as a parameter - the command HEAP FROGMAN, for 
example, shows all global handles assigned to the Program 
Manager. The LHEAP command shows the contents of a local 
heap whose selector is specified as a parameter to the com¬ 
mand. Although not exactly a memory command, VXD shows 
the memory location (as a linear address, rather than a selector) 
of every VxD. 

The VCALL command lists all of the services that may be 
called by a Virtual Device Driver. Even if a service is undocu¬ 
mented, once you have its name, you can step through the 
code with Soft-ICE/W to see what it does. 

Going a level deeper, into the CPU structures, the LOT and 
GDT commands show how the selector portion of a memory 
address maps to linear memory. They also reveal the contents 
of the full descriptor tables and their locations in linear 
memory. In a similar fashion, the IDT command shows the 
contents of the interrupt descriptor table. 

As you may already know, when Windows is running in 
enhanced mode, the linear address indicated by the descriptor 
table does not describe the physical address. For that informa¬ 
tion you need to know the linear-to-physical mapping defined 
by the CPU page registers. The PAGE command shows the 
mapping of the entire map or of a specified linear range. 

To reverse the process, that is, to find the linear address 
from a physical address, Soft-ICE/W provides the PHYS com¬ 
mand. For example, to find the linear address that addresses 
my Monochrome Display Adapter (MDA), I entered the com¬ 
mand "PHYS B0000." The response was a display of six linear 
addresses. The linear address OxOOOBOOOO corresponded to the 
local VM and the address 0x814B0000 corresponded to the 
fixed linear-to-physical mapping that Windows constantly 
maintains (i.e., linear = 0x81400000 + physical). 

Turning to the lowest-level configuration parameters of the 
CPU, the CR command displays the CR0, CR2 and CR3 registers 
(Intel does not define CR1). The TSS command shows the con¬ 
tents of the Task Switch Segment, an extremely low-level 
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structure used by the CPU to speed task switching. Because 
Windows performs task switching entirely in software, and 
uses the TSS only to specify which I/O ports are trapped to 
virtual device drivers, most of the TSS fields have no meaning. 

Debugging DOS Applications 

By loading Soft-ICE/W with Windows, you get a debugger 
not only for Windows applications, but also for DOS applica¬ 
tions. And, since the debugger itself runs in extended 
memory, all of the memory in a Windows virtual machine 
(VM) is available to the application - the debugger uses vir¬ 
tually none of the VM memory. 

To load symbols into Soft-ICE/W for a DOS application, you 
run the WLDR application in much the same way you run 
CodeView for DOS from the command line. From that point on, 
you have full debugging control of the application, as you 
would with any DOS debugger. With WLDR, though, you 
needn't worry about consuming real-mode memory or, since 
the debugger is already loaded, about waiting an inordinate 
amount of time for it to load. 

Debugging Windows Device Drivers 

With the exception of virtual device drivers (described 
later), Windows device drivers are really just DLLs that perform 
I/O to hardware. Although CodeView works well for debugging 
normal DLLs, it is not as useful for debugging the interrupt 
service routine (ISR) of a DLL. Because Soft-ICE/W is loaded 
separately from other Windows applications, it manages to 
bypass many of the problems related to debugging an ISR. It 
is always and completely resident, and the source code, once 
loaded, remains resident. Thus, it is easy to step through the 
source code of the ISR without having to worry about access¬ 
ing the disk. 

Debugging Virtual Device Drivers 

If you are writing or debugging a Virtual Device Driver 
(VxD), you’ll find Soft-ICE/W invaluable. 

The full set of commands available for debugging other 
code can be used in debugging a VxD. The notable difference 
is that, if you are running the debugger under the debugging 
version of the enhanced mode kernel ( WIN386. EXE), a few ad¬ 
ditional commands are available - specifically, all of the ''dot" 
commands listed in the SDK documentation for WDEB386! This 
is because these commands are actually implemented in the 
debugging version of WIN386 and not in WDEB386. Soft-ICE/W 
provides access to all of these commands, including those that 
relate to a VxD’s internal Debug_Query control. 

The only caveat is that you must include the /K switch on 
the WINICE command line when you start with the debugging 
version of WIN386. 

Using the Debugger 
Starting the Debugger 

Soft-ICE/W runs only with the 386 enhanced mode of Win¬ 
dows. To start the debugger, you run WINICE with optional 
parameters which specify how much memory to set aside for 
source files (which are kept in memory) and symbol table in¬ 
formation. In addition, you specify how much to set aside for 
a back-trace history buffer (described later). 


A final parameter, /LOAD, specifies any source files that 
need to be debugged during the Windows initialization phase 
- other files can be loaded later using the WLDR command. 
Source files for virtual device drivers or other base Windows 
device drivers might be specified here, along with the source 
file for any TSR that you load using the WINSTART.BAT file. 

The WINICE.DAT Configuration File 

Rather than specify parameters on the command line, you 
may include them in the WINICE.DAT configuration file, which 
also contains all of the key-to-function mappings. None of the 
Soft-ICE/W function keys are hard-coded - all may be 
remapped. 

As soon as it is loaded, Soft-ICE/w pops up its display and 
allows you to enter a command before Windows has begun. If 
you specify an INIT string in WINICE.BAT, Soft-ICE/W will ex¬ 
ecute any commands in the string at this first breakpoint. The 
initial value of the INIT string in WINICE.DAT simply contains 
a command that tells the debugger to proceed. You will see 
the debugger pop up and then disappear as Windows loads. If 
you are debugging from a remote terminal or from a separate 
display, you can change the INIT string to automatically 
switch to the alternate debugger console that you specify. 

The Debugger Display Windows 

The default debugger display consists of four windows 
which display, respectively, the CPU registers, a data block, 
code (source, assembly, or both), and interactive commands. A 
fifth window, the watch window, displays when a breakpoint 
you have specified is reached. The bottom line of the display 
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shows a status line in reverse video. The windows are stacked 
horizontally and their sizes can be changed freely. All but the 
command window can be removed from the display. 

Registers 

The register window shows all 32 bits of the CPU general 
purpose registers and all six of the 386 CPU segment registers. 
While this window can be toggled off and on, its size cannot 
be changed. 


ning the debugging version of Windows, the command win¬ 
dow also displays the Windows debugging output. 

Watch 

The watch window shows a list of user-entered addresses 
and their values. This window is initially blank, but appears 
when you enter the first address to watch. You can specify an 
address either in hexadecimal or by reference to its symbolic 
value (if the appropriate symbol table is loaded.) 


Data 

The data window displays one of four memory data blocks, 
each of which shows data starting from a specified address. 
The data can be displayed in byte, word, double-word, and 
floating-point formats. The DATA command specifies which of 
the four data blocks is to be displayed in the window. 

Code 

The code window shows code (typically starting at the cur¬ 
rent instruction) in one of three formats: source, assembly, or 
both. For disassembled code, the display of the actual code 
bytes can be suppressed, a feature particularly desirable for 
386 instructions, which may routinely be five or more bytes - 
useful when the actual bytes generated aren’t of particular 
interest. 

Command 

The command window shows keystrokes as they are 
entered and the responses from the debugger. If you are run- 
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The Status Line 

The status line usually reads “Soft-ICE/W is not active.” 
Despite this constant reminder, I often found myself typing 
commands into Windows, expecting the debugger to respond. 
Pressing Ctrl-D (or whichever key sequence you have as¬ 
signed) changes the display to "Enter a Command or ? for 
Help.” The help is extremely terse, but the status line will 
prompt you as you enter commands. 

Setting Breakpoints 

The procedure for setting a breakpoint in Soft-ICE/W fol¬ 
lows established conventions. The only difference from what I 
was accustomed to was that code breakpoints are entered 
with the BPX instead of the BP command. I suppose that this 
difference helps to distinguish between the breakpoint com¬ 
mand and the CPU register. 

Since Soft-ICE/W works only in enhanced mode, it is able to 
take advantage of the 386 debug registers, which means that 
you can set breakpoints in ROM or when data is accessed. 
Some debuggers offer this functionality, but actually simulate 
code execution, running the code at a severely slower pace. 
Soft-ICE/W lets the 386 hardware do the work, allowing your 
application to run at full speed until the breakpoint is reached. 

Backtracing 

Soft-ICE/W offers a backtracing capability that I found dis¬ 
appointing. With backtracing turned on, the debugger main¬ 
tains a buffer that contains a history of CS-.EIP values. Thus if 
you get to a breakpoint and need to know how you got there 
(not just that you did get there), you can enter the TRACE 
command to step through the instructions, in reverse order, 
that brought you to the current instruction. 

While this is useful, what I found frustrating is that the 
backtrace buffer did not contain any other information: I could 
not see what the register values were at each instruction. 
With WDEB386, since I can set a specific command to be ex¬ 
ecuted at a breakpoint, I can make the command display a 
register value, for example, whenever it hits the breakpoint, 
and then continue execution without requiring any interven¬ 
tion. I then have a history of precisely the information that I 
am interested in. I could find no way to do the same thing 
with Soft-ICE/W. 

Summary 

Overall, I found Soft-ICE/W to be an invaluable tool for 
debugging. Not only can it do things that are impossible with 
CodeView for Windows and WDEB386, but it is also relatively 
easy to learn and trivial to install. I found it to be reliable and 
consistent, and I expect to use Soft-ICE/W in place of other 
debuggers. □ 
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Programming Style 



Compile-Time Genericity 

Part 1 


About a year ago, I described a small variety of techniques for writing generic 
array-handling functions (see “Generic Functions in C and Pascal," TECH Specialist, vol. 
2, no.3: March 1991). A generic function performs the same conceptual operation on 
arguments of different types. For example, in that article I wrote a generic array 
comparison function called arraycmp that compares two arrays with elements of the 
same arbitrary type. That is, arraycmp can compare two arrays of integers, two 
arrays of the same struct type, or two arrays of whatever. The Standard C library 
functions bsearch and qsort are also generics. They too operate on arrays of any 
type. 

arraycmp, bsearch, and qsort all use a particular style that I call “run-time 
genericity." In this series of articles, I’ll contrast that style with a completely different 
approach that I call “compile-time genericity.” (To be more precise, I should call it 
“translate-time genericity," but I think compile-time genericity has a slightly better 
ring to it.) 
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In C, you Implement compile-time generics using macros; in 
C++, you implement them using a newly available feature 
called templates. In the popular PC dialects of Pascal, it’s es¬ 
sentially impossible to implement compile-time generics 
without using a preprocessor of some sort. I know of only one 
other language with true language-level support for compile¬ 
time genericity - Ada. I believe Eiffel also supports it, but I 
haven’t seen how. In any case, I’ll use C and C++ for my ex¬ 
amples. 

Reviewing Run-Time Generics 

I’d like to take another look at the implementation of ar- 
raycmp, the generic array comparison function 1 presented in 
my earlier article on generics. I want to contrast it with a 
special-purpose array comparison function, Temp, that works 
only for arrays of type T, where T is some previously defined 
typedef name. Listing 1 contains an implementation for Temp 
where type T is int. Listing 2 is the implementation and test 
program for the generic arrayemp from my earlier article. 

Temp accepts three arguments. The first two arguments, ol 
and a2, are the addresses of the arrays (with elements of type 
7) to be compared. The last argument, n, is the number of 
elements in each array. 

arrayemp has a longer calling sequence than Temp. Its first 
two arguments are also the addresses of the arrays to be 
compared, but they’re specified as const void * because 
they can point to arrays with elements of any type. As with 
Temp, arrayemp's third argument is also the number of elements 


Listing 2 (arrayemp) 

#include <stdio.h> 


#include <string.h> 

int strcf(const void *p, const void *q) 

/ 

typedef int (*cf t)(const void *p, const void *q); 

\ 

return strcmp(p, q); 

) 

int arrayemp 


(const void *al, const void *a2, size t n, 

/* 

size t size, cf t of) 

/ 

* Sample calls to arrayemp... 

const char *pl = a 1; 

int a[] = (1, 2, 3, 4, -5); 

const char *p2 = a2; 

int b[] = (1, 2, 3, 4, 4); 

size t i; 


int emp; 

double f[] = (1, 2, 3, 4, 5); 


double g [] = (1, 2, 3, 3, 4); 

for (i = 0; i < n * size; i += size) 


if ((emp = cf(pl + i, p2 + i)) != 0) 

char *s[] = ("123”, "456", “789"); 

return emp; 

char *t[] = ("123", "789", "456"); 

return 0; 


) 

int main(void) 

/* 

l 

printf("a vs. b = %d\n". 

* Some element comparison functions 

arraycmp(a, b, 4, sizeof(int), intef)); 

*/ 

printf("a vs. b = %d\n". 

int intcf(const void *p, const void *q) 

arraycmp(a, b, 5, sizeof(int), intef)); 

{ 

printf("f vs. g = %d\n", 

return *(int *)p - *(int *)q; 

arraycmp(f, g, 5, sizeof(double), doublecf)); 

I 

printf("s vs. t = %d\n", 


arraycmp(s, t, 3, sizeof(char *), stref)); 

int doublecf(const void *p, const void *q) 

printf(“s vs. t = %d\n", 

{ 

arrayemp(s, t, 3, sizeof(char *) , (cf t)strcmp)); 

if (‘(double *)p < ‘(double *)q) 

return 0; 

return -1; 

I 

else if (‘(double *)p == ‘(double *)q) 


return 0; 

/* End of File */ 

else 


return 1; 

i 


A General-Purpose Array Compai 

er in C Using Runtime Genericity 


Listing 1 

linclude <stdio.h> 
typedef int T; 

/* 

* Temp - compare two arrays of integers 
*/ 

int Tcmpfconst T *al, const T ‘a2, size_t n) 
{ 

int emp; 
size_t i; 

for (i = 0; i < n; ++i) 

if ((emp = al[i] - a2[i]) != 0) 
return emp; 
return 0; 

} 

/* 

* Sample calls to Temp... 

*/ 

int a[] = (1, 2, 3, 4, -5}; 

int b[] = (1, 2, 3, 4, 4); 

int main(void) 

{ 

printf("a vs. b = %d\n", Tcmp(a, b, 4)); 

printf("a vs. b = %d\n", Tcmp(a, b, 5)); 

return 0; 

) 

/* End of File */ 
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to be compared, arraycmp has two additional arguments: 
size and cf. size is the size (in bytes) of the elements in 
each array, and cf is a pointer to a function that compares 
array elements. 

arraycmp uses its size argument in computing the addres¬ 
ses of array elements, arraycmp needs this extra argument 
because its first two arguments, the array addresses, are 
const void *. A void * points to an object with incomplete 
type. That is, it points to an object with an unspecified size. 
Therefore, the caller must pass the array element size as a 
separate argument to arraycmp. 

Temp doesn’t need a separate size argument because its 
first two arguments address arrays whose element size is 
known at compile time. The compiler automatically translates 
an expression like al[i] into the proper address computation 
because it knows that al is an array of (or points to a) T. Each 
subscripting operation translates into code that multiplies i by 
sizeof(T) and adds the result to the base address of the 
array. (Actually, the compiler may replace the multiply with a 
faster operation during optimization, but the resulting code 
behaves as if the multiply were done.) 

arrayemp's last argument, cf, is a pointer to a comparison 
function - a function that compares two array elements. Since 
arraycmp doesn’t know what the array element types are, it 
doesn’t know what operator to use to compare them. So 
before you can compare arrays using arraycmp, you must 
write a comparison function for the element type in the ar¬ 
rays you wish to compare, and pass the address of that com¬ 
parison function as the last argument to arraycmp. 

Listing 2 shows a variety of different comparison functions, 
for elements that are int, double, and const char *. Every 
comparison function has the same prototype - one that ac¬ 
cepts two const void * arguments and returns an int. A 
particular comparison function must cast the void pointers 
into pointers to the actual element types it's supposed to 
compare. 

At first, Temp doesn’t appear to need an element com¬ 
parison function. It simply uses the predefined subtraction 
operator to compute the difference between corresponding 
elements of the arrays al and a2. This avoids the overhead of 
calling a function to perform what is normally a trivial arith¬ 
metic operation. This implementation of Temp works even for 
a few types other than int, like char or short int. Unfor¬ 
tunately, it doesn’t work when T is just about any other type, 
like double or const char *, so Temp really does need some¬ 
thing like a comparison function after all. Later I will examine 
ways to generalize Temp without incurring the run-time over¬ 
head of calling an out-of-line element comparison function. 

Well, um, aahh... 

When I first presented element comparison functions last 
year, I cautioned that calling a run-time generic function is 
generally less safe than calling a special-purpose version of 
the same function. I didn’t realize how right I was. 

Run-time generics rely heavily on void pointers and type 
casts, which are unsafe because they skirt the compiler’s 
ability to check data types. In effect, every time you use a 
void * or a cast, you are saying to the compiler "Yeah, yeah. 
I know you think this is unsafe, but I KNOW what I'm doing." 
When I wrote those comparison functions, I thought I knew 
what I was doing. But I didn't, stref is simply wrong. 


Jim Gimpel (of C-terp and PC-lint fame) caught the error 
while listening to the lecture on generic functions at C-Forum 
'91 last November. Rather than pounce, he had the compas¬ 
sion to wait until after the lecture to take me aside and point 
out the problem. A true gentleman. 

The problem is that stref loses one level of indirection 
through its pointer arguments. To see this, consider intef 
first, intef accepts two void pointers to objects that are ac¬ 
tually integers. If I could have written intef to preserve com- 
pile-time (static) typing, I'd have written it as 

int intcf(const int *p, const int *q) 

{ 

return *p - *q; 

} 

In other words, the "true" types of p and q are const int * 
intef in Listing 2 uses casts to reconstruct the “true" type 
before comparing the values. 

So what is the "true” type of the stref s arguments? stref 
accepts two void pointers to objects that are actually of type 
const char *. An implementation of stref that preserves 
compile-time type checking would be 

int strcf(const char **p, const char **q) 

{ 

return strcmp(*p, *q); 

} 
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Now note that the strcf in Listing 2 doesn't dereference 
pointers p and q before passing them to strcmp - strcf loses 
a level of indirection. The correct implementation is 

int strcf(const void *p, const void *q) 

{ 

return strcmp(*(const char **)p,*(const char **)q); 

} 

I should have recognized that strcf deviates from the pat¬ 
tern established by intcf and doublecf, namely, that the 
comparison function always dereferences its pointer argu¬ 
ments after casting from const void * to the 'true” type. But 
I didn't. My erroneous strcf omits both the casts and the 
dereferencing (*) operators. 

Thus, making mistakes calling run-time generics is even 
easier than I had previously thought. This experience presents 
a strong case for finding other ways of writing generics that 
preserve compile-time type checking. 

Macros as Generics in C 

Macros provide an easy way to write simple generic func¬ 
tions in C (and also C++). For example, 


computes the greater of two values of any type for which < is 
defined, as in 

int i, j, k; 

long double x, y, z; 

i = min(j, k); // uses int arithmetic 
x = min(y, z); // uses long double arithmetic 

These macros preserve compile-time type checking but may 
have unwanted side-effects, which may even affect the com¬ 
puted result. Unlike functions, which evaluate each argument 
expression only once, macros generate inline textual expan¬ 
sions that, when compiled, may evaluate some arguments 
more than once. For example, given 

long n, *p; 

the macro call 

n = abs(*p++); 

generates the expression 


#define abs(x) ((x) > 0 ? (x) : -(x)) 


n = ((*p++) > 0 ? (*p++) : -(*p++)) 


computes the absolute value for objects of any type for which 
> and - are defined. As another example, 


#define min(x, y) ((x) < (y) ? (x) : (y)) 



which evaluates *p++ twice, and probably returns the wrong 
result. 

Implementing generic functions as macros gets trickier for 
more complicated functions. Consider a macro called swop that 
exchanges the values of two objects of the same (arbitrary) 
type. You can write swap to expand as an expression, or as a 
statement. 

The expression version of swap is 

#define swap(a, b, t) \ 

((void) ((t) = (a), (a) = (b), (b) = (t))) 

Calling this macro is a little inconvenient because you must 
declare a temporary object for the macro to use, as in 

int i, j, t; 

swap(i, j, t); 

A statement macro can declare its own local variables and 
limit their scope using curly brackets. For example, the state¬ 
ment macro implementation of swap is 

#define swap(a, b, t) \ 

{ t _t; t = (a); (a) = (b); (b) = _t;} 

In this implementation, the third argument, t, is not the name 
of a temporary, but the data type of the operands, swap 
declares its own local variable of that type. A sample call 
looks like 

int i, j; 

swap(i, j, int); 
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Unfortunately, the curly brackets have their own little 
“gotcha!" The seemingly legal compound statement 

if (i < j) 

swap(i, k, int); 
else 

swap(j, k, int); 
actually expands to 
if (i < j) 

{ t _t; t = (a); (a) = (b); (b) = _t;}; 
else 

{ t _t; t = (a); (a) = (b); (b) = _t;}; 

causing a syntax error. The semicolon before the else ter¬ 
minates the if statement, leaving the else dangling. Tom 
Plum showed me a trick that gets around this problem - 
write swap as 

#define swap(a, b, t) \ 
do { \ 

t _t; t = (a); (a) = (b); (b) = _t; \ 

} while (0) 

Not very pretty, but effective. 

Overloading vs. Genericity 

In C++, you can avoid macro expansion side-effects by 
using inline functions instead. For example, 

inline int abs(int i) 

{ 

return i > 0 ? i : -i; 

) 


evaluates its argument only once (like a function), but 
generates code in line like a macro. A call such as 

long n, *p; 

n = abs(*p++); 


compiles as if it were 

{ 

long temp = *p++; 
n = temp > 0 ? temp : -temp; 

1 

The curly brackets around the expansion create a new block 
that limits the scope of temp. (Actually, the ini ine specifier on 
a C++ function is only a request to the compiler, like putting 
the register specifier on a data declaration. The compiler is 
not obligated to honor your request, and may compile a call 
to an inline as an out-of-line call. However, as compiler tech¬ 
nology improves, C++ compilers should get better at honoring 
such requests.) 

C++ also permits function name overloading - you can 
declare more than one function with the same name in the 
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same scope. For example, you can declare a different swap 
function for a wide variety of types, such as 

void swap(int *, int *); 
void swap(long *, long *); 
void swap(float *, float *); 
void swap(double *, double *); 

and so on. Then, if li and Ij are longs, 

swap(&li, &1j); 

compiles as a call to 

void swap(long *, long *); 

That is, the compiler generates a call to the function swap 
whose formal parameter list types match the actual argument 
types. 

Furthermore, C++ lets you eliminate the i’s (address-of 
operators) from the call and write 

swap(li, Ij); 

by using reference arguments instead of pointer types in the 
formal argument list, i.e., 

void swap(long &, long &); 
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Listing 3 


#include <stdio.h> 

int a[] = (1, 2, 3, 

4, -5); 

linclude <string.h> 

int b[] = (1, 2, 3, 

4, 4); 

linclude "arraycmp.h“ 

double f[] = (1, 2, 

3, 4, 5); 

/* 

* Some element comparison functions 

double g[] = (1, 2, 

3, 3, 4); 

char *s[] = ("123", 

“456", "789“); 

*1 

char *t[] = ("123", 

"789", "456“); 

Idefine intcf(i, j) ( (i ) - (j)) 
arraycmp implement(int); 

int main(void) 

/ 


inline int doublecf(double d, double e) 

\ 

printfp'a vs. b 

= %d\n", 

1 

arraycmp(a. 

b, DIM(a) - 1)); 

return d<e?-l:d==e?0:l; 

printf("a vs. b 

= %d\n“. 

1 

arraycmp(a, 

b, DIM(a))); 

arraycmp implement(double); 

printf("f vs. g 

= %d\n". 


arraycmpff. 

9, DIM(f))); 

typedef const char *str; 

printf("s vs. t 

= %d\n", 

Idefine strcffs, t) strcmp((s), (t)) 

arraycmp(s. 

t, DIM(s))); 

arraycmp implement(str); 

return 0; 

1 


/* 

* Sample calls to arraycmp... 

*/ 

Idefine DIM(a) (sizeof(a) / sizeof(a[0])) 

/* End of File */ 



When you declare an argument as a reference, the function 
call passes the address, rather than the value, of the cor¬ 
responding actual argument. 

To a novice programmer, an overloaded swap function writ¬ 
ten with reference arguments can look, a lot like a generic. In 
fact, it's even easier than using the macro versions of swap, 
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because both forms of the macro require an additional argu¬ 
ment (either the name of a temporary or the type of the 
arguments). Using the overloaded swap functions, the 
programmer writes a call to a function named swap, and the 
compiler applies the swapping algorithm appropriate for the 
actual argument types. 

But function name overloading isn't genericity. An over¬ 
loaded function like swap only works for the fixed set of types 
for which it has been defined. Whenever you define a new 
type, and you want to be able to call swap for operands of 
that type, you must define yet another swap function, swap is 
very simple, so defining another swap isn't that much of a 
chore. But for more complicated operations, writing yet 
another version is tedious and error-prone. The whole point of 
writing generics is to avoid that rewriting. 

Generating Out-Of-Line Generics 

Although you can package a large generic function as 
statements that expand in line, you may waste a lot of code 
space, because each function call generates an entire copy of 
the function body. Rather, you define macros that let you in¬ 
stantiate a single object-code copy of a generic function for 
each type of argument. For example, the macro arraycmp_im- 
plement(T) defines an instance of arraycmp that accepts ar¬ 
guments of type const T *. If you call 

arraycmp_implement(double) 

it expands to 

int arraycmp 

(const double *al, const double *a2, size_t n) 

{ 
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In other words, the macro call expands to a complete defini¬ 
tion for an instance of the generic arraycmp function that 
preserves compile-time type checking. 

To avoid duplication of the object code in other source 
modules, you also need a macro arraycmp_declare(T) that 
simply declares (but does not define) an instance of arraycmp 
that accepts arguments of type const T *. That is, the call 

arraycmp_declare(doubl e) 

expands to 

int arraycmp 

(const double *al, const double *a2, size_t n); 

Once you instantiate the generic, you can call it as you would 
any other function. Listing 3 provides some sample instantia¬ 
tions and calls in greater detail. 

This implementation of arraycmp still depends on the prior 
definition of element comparison functions. However, as 
shown in Listing 3, the element comparison functions can be 
implemented as macros, inline functions, or ordinary (non-in- 
line) functions. For example, the instance of arraycmp for ar¬ 
rays of int uses the macro intcf for its comparison function. 
The comparison function for arrays of double uses an inline 
function called doublecf. The comparison function for arrays 
of str (defined as const char *) is a macro that expands to 
a call on the standard library function strcmp. Furthermore, 
the comparison functions in Listing 3 are completely type-safe 
- they use neither void pointers nor type casts. arraycmp_im- 
plement expands to a copy to arraycmp that checks its argu¬ 
ments at compile-time. 

The macro definitions for arraycmp_declare and ar- 
raycmp_implement appear in Listing 4. Both macro definitions 
span more than one line of text, so all but the last line of 
each have a backslash (\) to continue the macro definition to 
the next line, arraycmp_ impl ement(T) uses the C preprocessor 
"token-pasting’’ operator ## to append the suffix cf to the 
type name 7, forming the name of a comparison function. 
Thus, for example, the if statement in the macro call ar- 
raycmp_implement(int) expands as 

if ((cmp = intcf(al[i], a2[i])) != 0) 

but since intcf is itself a macro, it in turn expands as 

if ((cmp = ((al[i]) - (a2[i]))) != 0) 

This macro implementation of a generic arraycmp function is 
what I call a "compile-time” generic. That is, the macro 
provides a template for manufacturing new instances of ar¬ 
raycmp that operate on different types. Each instance is as 
efficient and type-safe as a special-purpose version of ar¬ 
raycmp hand-written for a specific array element type. 

More to Come 

This implementation of arraycmp works for C++ but not C 
because it uses function name overloading. The macro techni¬ 
ques can be enhanced to avoid overloading so that it can be 


Listing 4 (arraycmp.h) 

Idefine arraycmp_declare(T) \ 

int arraycmp (const T al [], const T a2[], size_t n) 

Idefine arraycmp_implement(T) \ 
arraycmp_declare(T) \ 

{ \ 

size_t i; \ 
int cmp; \ 

\ 

for (i = 0; i < n; ++i) \ 

if ((cmp = T II cf(al[i], a2[i])) != 0) \ 
return cmp; \ 
return 0; \ 

) 

/* End of File */ 


A General-Purpose Array Comparer in C++ 
Using Compile-Time Genericity 


used with C. However, the technique still has some deficien¬ 
cies. 

Next time, I’ll critique the different approaches, and explain 
how and why C++ templates are an even better way to im¬ 
plement compile-time generic functions. □ 
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Tech Tips 



Edited by 
Leor Zolman 


Please send us your best 
tricks and hacks -those 
clever pieces of code to 
make things work the way 
they should! You'll receive 
at least $50 for each tip 
that we print 
Send your submissions to.- 
Tech Tips 
Leor Zolman 

1601 W. 23rd St, Suite 200 
Lawrence, KS 66044-2743 
or email 

techtips@rdpub.com. 


Copying Large Data Chunks in C 


Prof. Berthold K. P. Horn 
M.I.T. Artificial Intelligence Laboratory 
545 Technology Square 
Cambridge, MA 02139-4307 

Recently, I ran into a problem reading in and setting up bitmaps greater than 64K 
bytes in size. This cannot be done by reading directly into some storage area, be¬ 
cause the basic read commands can’t handle more than 64K bytes at a time. 

One way to perform the task is by looping and using huge pointers, but that 
approach is very slow. So, my code divides the operation up into chunks, each of 
which can be copied using just far pointers. 

Listing 1 shows a little function that will copy from a near buffer to somewhere 
in a huge array without getting into trouble at segment boundaries and without 
using huge pointers in the copy operation, which would slows things down a lot. 

This code can be easily modified to read directly into the huge array by splitting 
the reads in a similar fashion. I need to do some preprocessing of the data in any 
case, so I read it into a locally allocated buffer first. Several people made suggestions 
on how to do this efficiently. 



Leor Zolman has been involved with microcomputer programming for 15 years. He is 
the author of BDS C, the first C compiler targeted exclusively for personal computers. 
Leor's first book, Illustrated Q is now available from R&D Publications, Inc. Leor and 
his family live in Lawrence, KS. 



















This technique is a little sneaky in 
that it involves operations to decom¬ 
pose and address into segment and of¬ 
fset - something most C programmers 
don't normally do. 

I found I couldn't use memcpy() in 
place of the *d++ = *u++ loops, be¬ 
cause the intrinsic version of memcpy 
can't handle far pointers (while the 
subroutine version can - at least with 
MSC). 

Thanks to Risto Larkin and other In¬ 
ternet folks for their assistance in the 
evolution of this code. 



Alternatives to the Three- 
Fingered Salute 


Tony Ingenoso 
1323 S.E. 17th #274 
Ft. Lauderdale, FL 33316 


Here are two programs, BOOT.SYS 
(source is BOOT.ASM, Listing 2) and 
TSRBOOT.COM (source is TSRBOOT.ASM, 
Listing 3), along with the MAKEFILE (List¬ 
ing 4) that will build them. 

BOOT.SYS is a device driver which 
will reboot the PC whenever it detects 
an NMI (Non-Maskable Interrupt). This 
can be handy if you have some debug¬ 
ging hardware that’s capable of causing 
an NMI, like the Periscope and Atron 
software probes. Being basically lazy, I 
find it easier to just punch the NMI but¬ 
ton than to hit Ctrl-Alt-Del. 

Some people, particularly hand¬ 
icapped folks, might find this extremely 
useful if hitting Ctrl-Alt-Del is a real 
hassle for them. On the old PC and AT 
keyboard layouts, doing Ctrl-Alt-Del 
is a two-handed operation even for an 
able-bodied person. If you're working 
with a mouth stick the situation could 
be grim indeed. 

This device driver illustrates a few 
handy tricks: 

• When initializing, it alters the inter¬ 
rupt routine pointer in its device 
header to point to a smaller "mini’’ 
routine used for any post-init re¬ 
quests that come along. This reduces 
the resident memory requirements 
of the device driver. 

• Since it's a character device, I put 
blanks as the leading characters in 
the device's name. This makes it har¬ 
der for some unsuspecting application 


Listing 1 

finclude <dos.h> 

/* Copy bytes from NEAR buffer to HUGE array - using FAR pointers */ 

/* Split up copy operation where it crosses segment boundary */ 

void hmemcopy(char huge *to, char *from, unsigned long count) { 
unsigned int offset, k, n; 
char huge *toend; 
char far *d; 
char *s; 

toend - to + count - 1; /* last byte destination */ 

while (FP_SEG(to) !■ FP_SEG(toend))( /* will it cross boundary ? */ 

offset - FP_OFF(to); /* calculate how much left in segment */ 

if (offset == 0) ( /* special case - do in two pieces */ 

n * 32768; /* copy first half */ 

d • to; s * from; 

for (k = 0; k<n; k++) *d++ = *s++; 

to += n; from += n; count -- n; offset += n; 

) 

n - 65535U - (offset - 1); I* avoid arithmetic problems */ 
d - to; s = from; /* copy up to end of segment */ 

for (k = 0; k < n; k++) *d++ - *s++; 
to +- n; from +■ n; count -* n; 

) 

d = to; s * from; n - (unsigned int) count; /* now do last piece */ 
for (k * 0; k < n; k++) *d++ = *s++; 


/* End of File */ 


Listing 2 


BOOT.SYS Illustrates some DOS device driver tricks. 


This simple device driver will reboot the PC whenever an NMI is 
intercepted. This is convenient for folks with a Periscope breakout 
switch or an Atron probe. The IBM Professional Debugger package also 
included an NMI card, but the switch is on the card and not so convenient. 

This device driver could also be useful to a handicapped person where 
hitting Ctrl-Alt-Del is a difficult or impossible task depending on 
their keyboard layout. 

Many times a device driver will want to hook some vectors during init 
time and then not accept any I/O requests after that. All the work it 
does is in it's interrupt handler(s). The problem with this is that 
after init, the device is left with a larger DO interrupt routine than 
is needed if all it's going to do is reject all requests. By having the 
device's init code redirect the interrupt routine pointer in the device 
header to a shorter “mini" DD interrupt routine we can set the ending 
address of the device driver such that the larger initial interrupt 
routine is part of the code to be thrown away after initialization. 

This results results in smaller resident memory requirements for the 
device driver. 

By setting the symbol $AVE_MEMORY below to 0 or 1 the device driver can 
be built with or without the interrupt routine hack. On my development 
system running DR-DOS 6.0, the trick saved a paragraph of resident memory. 
Other device drivers may save a bit more. 

Another trick used below has to do with the name of the device. I always 
worry about character devices invading the name space that the DOS file 
system uses when writing a device like this one, which is never intended 
to do I/O. By having blanks at the start of the device name in the 
device header, we lessen the possibility of some DOS app stumbling across 
this device driver by accident. 


Yet another trick used below is to place a '$' right after the device 
header. This allows the string in the device header to be used to 
print the device name during initialization via Int 21 fn 9. 


WARNING: This code WON'T 
operation, like 

WORK on systems that use NMI for normal system 
the PCjr and PC convertible. 

Tony Ingenoso 

1323 SE 17th #274 

Ft. Lauderdale, FL 33316 
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to stumble across the device by acci¬ 
dent. Since this device rejects all re¬ 
quests other than “init," it's not very 
useful to applications anyway. 

• 1 put a “$" character right after the 
device header. This makes it easy to 
display the device name via Int 21H 
function 09H as the device initializes. 
TSRBOOT.COM is a TSR version of 
BOOT.SYS which is compatible with all 
versions of DOS back to 1.0. It illustrates 
a trick which can be used for small 
TSRs. It relocates its working code into 
a safe spot in the PSP, then throws itself 
away, along with some of the PSP, 
when it goes resident. This is handy for 
reducing the resident size of small TSRs 
to the bare minimum. 

The device driver version of the NMI 
reboot uses less memory than the TSR 
version. Table 1 gives the memory 
usages I measured on various versions 
of DOS (all values are in bytes as 
measured with CHKDSK). 

After completing this little exercise, it 
seems that the moral of the story is that 
sometimes a TSR may not be the way to 
go when memory is at a premium. 
Maybe the same code packaged in 
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Subscribers 

Occasionally, Windows/DOS 
Developer's Journal makes its 
mailing list available to vendors 
of products we think our 
readers will find interesting. Cur¬ 
rent subscribers receive free in¬ 
formation in the mail from 
these vendors. 
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not be used in these mailings, 
please let us know. Just copy or 
clip this form and send it with 
your name and address to: 
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Listing 2 — Cont’d 

SAVE_MEMORY - 0 


Device driver request header structure 


request_header struc 
len db ? 

unit db ? 

command db ? 

status dw ? 

reserve db 8 dup (?) 

;— init specific — 
nunits db ? 

endaddr dd ? 

request_header ends 


Dummy segment where the BIOS lives 


bios 

segment at OFFFFH 



assume 

cs:bios 



org 

0 


boot 

label 

far 

; Jumping here reboots the PC 

bios 

ends 




cseg segment 

para public ’CODE 1 


assume 

cs:cseg 


org 

0 


» 

DEVICE HEADER - 


dd 

-1 

Link to next device 

dw 

8000H ; 

Character device 

dw 

offset strategy ; 


intaddr dw 

offset interrupt: 

Initially point to large interrupt routine 

devname db 

1 BOOT 1 , 1 $ 1 : 

Blanks prevent stumbling on dev by accident 

req_ptr label 

dword 

; Strat saves RQH pointer here 


rh offset 

dw 

? 

rh_seg 

dw 

? 


NMI 

trapper routine 


NMItrapper proc far 

mov ax, 0040H 

mov ds, ax 

mov word ptr ds:[72H],1234H 

jmp boot 

NMItrapper endp 


DD strat routine 


strategy proc far 

mov cs:rh_offset, bx ;offset 

mov cs:rh_seg, es ;segment 

ret 

strategy endp 
IF SAVE MEMORY 


DD interrupt routine for post-INIT requests. 


Using this mini interrupt routine after init 
reduces the resident memory requirements of 
the device driver. 


mini_interrupt 

proc far 



push 

ds 



push 

si 



Ids 

si, cs:req_ptr 

DS:SI-->request 

header 

mov 

[si].status, 8103H 

Status = Done + 

Error + Unk command 

pop 

si 



pop 

ds 



ret 




mini_interrupt endp 




THR0W_AWAY_C0DE label near 
ENDIF~ 


Set BIOS reset flag 
WARM 

JMP FFFF:0000 
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Listing 2 — Cont’d 


DD interrupt routine for INIT requests 


nterrupt proc far 


push 

ds 

Save what gets whacked 

push 

si 


push 

ax 


Ids 

si, cs:req ptr 

DS:SI-->request header 

mov 

al, ds:[sij.command 

AL == command code 

cmp 

al, 0 

Is It an Init request? 

jne 

error 

All but INIT get error 

call 

initialize 


mov 

ax, 0100H 

Status = No error + Done 

jmp 

short exit 


error: mov 

ax, 8103H 

Error + Done + Unknown 



command 

exit: mov 

ds:[si].status, ax 

Set status word in RQH. 

pop 

ax 

Restore 

pop 

si 


pop 

ds 


ret 



interrupt endp 



IF (SAVE MEMORY EQ 0) 


THROW AWAY CODE 

label near 



NDIF 




Initialize the device 


nitialize proc 

near 


push 

dx 

Save DX 

push 

cs 

DS==CS 

pop 

ds 


assume 

ds:cseg 


IF SAVE_MEMORY 




Relocate the 

DD's Interrupt routine to 

the "mini". 


mov 

word ptr intaddr, offset mini interrupt 

ENDIF 




Display the logo message 



mov 

ah, 09H 

Display the logo 

mov 

dx, offset logo 


int 

21H 



Grab the NMI 

vector. 



mov 

ax, 2502H 

NMI is Int 2 

mov 

dx, offset NMItrapper 


int 

21H 



Show the name 

of the initializing device 


mov 

ah, 09H 


mov 

dx, offset devinil 

; Display "Device [" 

int 

21H 


mov 

dx, offset devname 

; Display the device name 

int 

21H 


mov 

dx, offset devini2 

; Display "] initialized." 

int 

21H 



Set the ending address. 



Ids 

si, cs:req ptr 

; Get RQH pointer back 

assume 

ds:nothing 


mov 

word ptr [si].endaddr, offset THROW AWAY CODE 

mov 

word ptr [si].endaddr+2. 

cs 

pop 

dx 

; Restore DX 

ret 




initialize endp 



Messages 


logo db 

'BOOT VI.00, Reboot on NMI',13,10 

db 

'Tony Ingenoso, 1992',13,10,'$' 

devinil db 

'Device [$' 


devini2 db 

'] initialized.',13,10,' 


cseg ends 



end 



; End of File 
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Listing 3 


TSR version of the NMI rebooter (it even works on DOS 1.0) 
Tony Ingenoso 


; Should we free the environment? 


mov 

int 


ax, 3000H 
21H 


Get version 


; 1323 

SE 17th 

#274 


cmp 

al, 0 ; Is it l.X? 

; Ft. 

Lauderdale, FL 33316 


je 

GoResident ; l.X doesn't have environments 

bios 

segment at OFFFFH ; 

Dummy segment where the BIOS lives 

> 

; Free the space used by the environment. 


assume 

csrbios ; 





org 

0 ; 


mov 

es, word ptr cs:[2CH] ; PSP[2CH]— >environment 

boot 

label 

far ; 

Jumping here reboots the PC 

mov 

ah, 49H ; Free memory block 

bios 

ends 



int 

21H 

cseg 

segment para public 'CODE 


; Compute ending address and stay resident 


assume 

cs:cseg,ds:cseg.es:nothing.ss:cseg 




org 

100H 


GoResident: 


start 

label 

near 


mov 

dx. (5CH + TRAPPER LEN + 1) 





int 

27H ; 1.0 compatible TSR 

Display the logo 





mov 

ah, 09H 

; Display string 

; NMI trapper routine (gets moved up into PSP) 


mov 

dx, offset logo 





int 

21H 


NMItrapper proc far 





mov 

ax, 0040H ; Set BIOS reset flag 

Relocate the 

trapper routine to 

a safe spot up in the PSP to save space. 

mov 

ds, ax ; 

We move it on 

top of the default 

FCB's since we're not going to use them. 

mov 

word ptr ds: [72H],1234H ; WARM 





jmp 

boot ; JMP FFFF:0000 


cld 



TRAPPER LEN EQU J-NMItrapper 


mov 

si, offset NMItrapper ; Location of trapper code 

NMItrapper endp 



mov 

di, 005CH 

; Location of first FCB 




mov 

cx, TRAPPER LEN 

; # of bytes to move 




rep 

movsb 



Messages 

Grab 

the NMI 

vector 


logo db 

'TSRBOOT VI.00, Reboot on NMI',13,10 





db 

'Tony Ingenoso, 1992',13,10,'$' 


mov 

ax, 2502H 

; Set vector 

cseg ends 



mov 

dx, 005CH 

; DS:DX-->NMI trapper routine 

end 

start 


int 

21H 


; End of File 



Listing 4 


#- . - . 

# This makefile builds the device driver BOOT.SYS and the TSR 

# TSRBOOT.COM 

# 

# I use Borland's Turbo Assembler and Turbo Linker. If you've 

# got some other language products you may need to tweak the 

# makefile a bit. I'm running DR-DOS 6.0 on my development system 

# and they've provided EXE2BIN with DR-DOS. 

# . 

# Use these for Microsoft stuff 
#ASM = MASM 

#LNK = LINK 

# Use these for Borland stuff 

ASM = TASM 

LNK = TLINK 

all : boot.sys tsrboot.com 

boot.sys : boot.asm 
$ (ASM) boot; 

$(LNK) boot.boot,nul; 
exe2bin boot.exe boot.sys 
del boot.exe 

tsrboot.com : tsrboot.asm 
$(ASM) tsrboot; 

$(LNK) tsrboot.tsrboot.nul; 
exe2bin tsrboot.exe tsrboot.com 
del tsrboot.exe 


device-driver format will be more economical with memory. 
This is particularly true if the TSR wouldn't lend itself to the 
relocation trick I used in TSRBOOT.COM. Without the trick, the 
resident size of the TSR would probably have been bigger by 
around 160 bytes in most cases. 

The TSR is also burdened with the problem of the process's 
environment area in DOS 2.0 and later. Most TSRs don't look at 
the environment and free it up as TSRBOOT does. A block 
freed in this way, however, isn't going to be contiguous with 
the rest of DOS’s free memory, which limits its usefulness. 
Device drivers aren’t affected by this problem. 

The downside with a device driver is that it's fairly limited 
in the Int 21H calls it can do when initializing. TSRs don’t 
have this limitation. 


Table 1 

DOS version 

BOOT.SYS 

TSRBOOT.COM 

PC-DOS 1.0 

N/A 

112 

PC-DOS 1.1 

96 

112 

PC-DOS 2.0 

96 

128 

PC-DOS 2.1 

96 

288 

PC-DOS 3.1 

96 

128 

PC-DOS 3.2 

96 

128 

PC-DOS 3.3 

96 

128 

PC-DOS 4.0 

112 

128 
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Call For Papers 


Windows/DOS Developer’s Journal 

is seeking articles on the following 
topics. If you have an idea for a related 
story and experience that would espe¬ 
cially qualify you to write on one of 
these topics, contact our editorial staff 
for Author Guidelines at: 

Windows/DOS Developer’s Journal 

1601 West 23rd St., Suite 200 

Lawrence, KS 66046-2743 
(913) 841-1631 

FAX (913) 841-2624 

Proposals should include a short 
abstract, preferably followed by a 
one-page outline of the article. A brief 
resume of the author's qualifications 
should accompany the proposal. 

Graphics 

Number Crunching 

Networks 

■ Proposals due 6/5/92 
manuscripts due 7/13/92 
Suggested topics: A C++ class 
library for Windows graphics. Program¬ 
ming a graphics coprocessor. How to 
use color effectively in Windows ap¬ 
plications. An Epson emulator for 
PostScript devices. 

■ Proposals due 7/9/92 
manuscripts due 8/13/92 
Suggested topics: How to program 
the Weitek coprocessor. Using an 
i860 multi-processor board for num¬ 
ber crunching. Tips on writing optimal 
80x87 code. How to write a Windows 
program in FORTRAN. Programming 
a floating-point array processor. 

■ Proposals due 8/6/92 
manuscripts due 9/11/92 
Suggested topics: Using Windows 
3.1 network support functions. Dis¬ 
tributed PC processing across LANs. 
Designing LAN-aware applications. 


Both of these programs were tested under the DOS ver¬ 
sions mentioned in the above table, on the systems listed 
here. The NMI card from an Atron software probe was used in 
all cases to produce the NMIs. 

• IBM PC/XT, 640K, 1.6Meg of EMS, 360K A:, 720K B:, 8087, (2) 
ST-238 RLL drives, Herc+ graphics card 

• IBM PC/AT, 2.6Meg, 1.2M A:, 360K B:, 30Meg hard file, IBM 
VGA card 

I also tried both programs on a no-name XT clone with 384Kb, 
a single floppy, 8087, an IBM mono display card, and a Central 
Point Copy2PC option card. This machine has an Atron 
hardware probe and the NMI card that came with the IBM 
Professional Debugger package. I used the IBM Professional 
Debugger card to generate the NMIs on this system, but I only 
tried DOS 2.1. 

The TSR version seems to work in the OS/2 1.3 DOS box. I 
don’t recommend using it here though, because you'll blow 
away any background tasks and, if the system is running HPFS 
with lazy write, you could lose data too. The device driver 
version won’t work under OS/2 because it uses Int 21’s during 
its initialization. It could be changed, however, to use BIOS Int 
10’s for its messages and a direct vector rip-off to take the 
NMI vector. Then it would probably work. The same caveats 
about the TSR version apply. □ 
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Would you know one 
if you saw one? 



Protect the integrity of your C-language programs with C-Verify “ 
and C-Debug',“ two utilities from Softran" 

C-Verify, Softran’s newest product, is a coverage analyzer for 
testing C-language programs. It generates a report of every branch 
taken—and not taken—through your program, assuring you of 100 
percent test coverage! 

C-Debug is a pointer checker which, according to Unix Review, 
“excells at finding pointer problems in code." When used with 
C-Verify, it offers you the highest quality assurance possible in 
C-language programming. C-Verify and C-Debug can be run at the 
same time and work with all C compilers. Both are available for MS- 
DOS and UNIX systems. To order, call 1-800-462-3932. (In Canada, 
call 1-708-505-3456.) 


Softran Corporation 

One Naperville Plaza, Suite 455 

Naperville, IL USA 60563 


□ Request 344 on Reader Service Card □ 

Windows/DOS Developer’s Journal — Page 63 


Softran 


CORPORATION 








New Products 

Industry-Related News & Announcements 


Genus Updates Suite of Products 

Genus Microprogramming has released new versions of 
three of their products: PCX Toolkit, GX Graphics, and 
Proteus. 

PCX Toolkit v5.0 allows developers to display any num¬ 
ber of images of any size, at any point on the screen. You 
can scroll images within windows, scale them to any size, 
capture and convert screens from other programs, print 
black and white images, scale images, inspect image 
headers, translate text screens into PCX images, fix older PCX 
files, and more. This version includes new color conversion 
and image resolution functions and VESA support In addition 
to conventional, expanded, and disk-based memory, PCX 
Toolkit v5.0 now supports XMS extended memory. 

GX Graphics v2.0 allows you to replace your existing 
graphics library to make your programs faster, smaller, and 
more portable across compilers while supporting more video 
modes. The library includes over 175 functions and supports 
logical operations, clipping, world coordinates, mouse 

Microsoft Automates Windows Testing 

Microsoft has released Microsoft Test for Windows, a 
graphical testing tool designed to create and run automated 
test scripts for Windows applications. The tool contains a re¬ 
corder that generates Basic code for simple test scripts by 
recording keystrokes and mouse movements. You can edit 
the code the recorder generates. 

FastTest is a subset of the Microsoft Test Basic that uses 
defaults and high-level English-like functions to create test 
scripts. Users with no programming experience can write 
test scripts using FastTest 

Microsoft Test can run unattended tests and log the 
results. The tool can test events such as interapplication mes- 

Eiffel Comes to PCs 

Interactive Software Engineering has started shipping the 
first DOS version of Eiffel in the United States. Eiffel/S comes 
with a compiler that produces C code from Eiffel source and 
features a set of libraries, basic classes, I/O classes, persist¬ 
ence classes, and data structures. This version of the com¬ 
piler implements Eiffel v3 as described in Eiffel: The 
Language, published by Prentice Flail. 

FTM Correction 

Ancier Technologies' FastFont Typeface Manager (FTM) is 
a library of 20 high-level C functions that supports three 
typeface families: COBB, DIXON, and MARIN (similar to 
Courier, Flelvetica, and Times Roman). FTM costs $495 and is 
royalty-free. 

Additional options include Atech's Virtual Printer Driver 
Platform, AllType typeface conversion utilities, Scalable Pic- 


routines, text, and drawing to virtual buffers. This version in¬ 
cludes new functions for event processing, world coor¬ 
dinates, clipping, and viewports. Genus has optimized many 
existing drawing functions and added several new ones. 

Proteus v6.0 is a prototype/demo tool that lets users test 
design ideas and create sample interfaces without having to 
write code. The product allows you to create demos and 
software prototypes that are interactive and combine text 
on graphics with custom sounds and music. The package 
supports over 35 video and animation effects such as fades, 
wipes, explodes, splits, spirals, weaves, and blinds, each 
paintable at variable speeds for special effects. Proteus v6.0 
supports conventional, expanded, and disk-based memory. 

PCX Toolkit v5.0 costs $249, $599 with source code. GX 
Graphics v2.0 costs $199, $699 with source code. Proteus v6.0 
costs $395 or, in a Limited Edition, $199. For more information, 
contact Genus Microprogramming 2900 Wilcrest, Suite 145, 
Houston, TX 27042-3355, (713) 870-0737 or (800) 227-0918. 


sages and can trap unexpected events such as UAEs and 
take pre-specified actions, such as logging conditions of the 
event or starting another test One of the utilities in the pack¬ 
age can capture and compare Windows controls such as 
menus, buttons, and dialog boxes. Another utility captures 
and compares screen bitmaps. 

Microsoft Test costs $395 and comes with a full set of ref¬ 
erence manuals, including a 575-page user's guide and con¬ 
text-sensitive online help. For more information, contact 
Microsoft Corporation, One Microsoft Way, Redmond, WA 
98052-6399, (206) 882-8080; FAX (206) 936-7329. 


Eiffel for DOS costs $595 and requires a 286 or better 
with at least 2Mb of memory. The OS/2 version costs $1,200 
and an Atari TOS version costs $185. Educational discounts 
are available. For more information, contact Interactive 
Software Engineering, Inc., 270 Storke Road, Suite 7, 
Coleta, CA 93117, (805) 685-1006; FAX (805) 685-6869. 


ture Manager, and more than 300 typefaces. (These options 
were incorrectly listed as part of the FTM package in the 
April 1992 New Products column.) 

For more information, contact Ancier Technologies, Inc., 
5964 La Place CL, Ste. 125, Carlsbad, CA 92008, (619) 438- 
5004x132 or (619) 438-6883; FAX (619) 438-6898. 
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Lahey Adds DPMI Support 

Lahey Computer Systems, Inc, has released F77L-EM/32 
v5.0, a new version of their Fortran for 386 and 486 
machines. This version comes with a customized version of 
Phar Lap's 3861 DOS-Extender that supports VCPI, XMS, and 
DPMI memory management The DPMI-compliant DOS ex¬ 
tender allows EM/32 users to take full advantage of ex¬ 
tended memory while running in a DOS box under Windows. 
The new version of the compiler supports arrays greater 
than 16Mb, up to 255 open files per program unit and sub¬ 
string bounds checking. 

This version includes a new version of Lahey's Source On- 
Line Debugger (SOLD). This version is a 32-bit protected- 
mode debugger that runs up to 30 times faster than the 

object-Menu Provides GUI for DOS C++ 

object-Menu is a new toolkit that allows graphics 
developers to quickly add a GUI to their DOS C++ applications 
with an OSF/Motif look. object-Menu provides an object- 
oriented, event-driven framework for implementing user in¬ 
terfaces with windows, menus, dialog boxes, keyboard and 
mouse support, and even a hypertext help system. 

object-Menu provides a window system that deals with 
window events and overlapping windows, restoring underly¬ 
ing windows without requiring the application to regenerate 


real-mode debugger included with previous versions of 
EM/32. The new debugger also allows programmers to break 
and trace execution at specified Fortran statement labels. 

F77L-EM/32 v5.0 costs $1195 and requires a 386/486SX 
with a math coprocessor or a 486DX, DOS 3.3 or higher, and 
2Mb of extended memory. The package is royalty-free and 
developers can distribute their DOS-extended Fortran applica¬ 
tions without any additional fees. For more information, con¬ 
tact Lahey Computer Systems, Inc, P.O. Box 6091, 865 
Tahoe Blvd., Incline Village, NV 89450, (800) 548-4778 or 
(702) 831-2500; FAX (702) 831-8123. 


the image. The package supports horizontal and vertical 
menus (normal and tear-off), attached and aligned or 
■popped up.” Menus can include buttons, check marks, and 
user-defined icons. 

object-Menu costs $369, or $529 with source. The pack¬ 
age supports Turbo C++, Borland C++, and Microsoft C++. For 
more information, contact Island Systems, 7 Mountain 
Road, Burlington, MA 01803, (617) 273-0421; FAX (617) 
270-4437. 


Toolkit Helps Create Text/Graphics SAA Interfaces 


QuickWindows Advanced for C is a new, SAA-compliant 
user interface library that works in both text and graphics 
modes through SVGA. The library is written completely in as¬ 
sembly language, typically adds 12Kb to 30Kb to programs, 
and does not require Windows or any external graphics 
libraries. Over 180 functions allow C programmers to add 
windows, popup and pulldown menus, context-sensitive 
help, dialog boxes, icons, fonts, mouse support, and DOS sup¬ 
port to their programs. 

A dialog box can contain command buttons, radio but¬ 
tons, check boxes, vertical and horizontal scrolling tag and 
list boxes, text input boxes, formatted picture field data 
entry boxes, rangebars, 3-D graphical icon buttons, and user- 
definable dialog objects. Programmers can control the styles 
and colors for anything in the QuickWindows system. 

QuickWindows can switch between text and graphics 
modes just by changing the screen mode. The package also 


supports static and dynamic icons. Dynamic icons can be in¬ 
tegrated into a dialog system and made to function as 3D 
command buttons, radio buttons, or checkboxes. You can 
also import Windows icons with an optional $29 icon con¬ 
verter. 

QuickWindows Advanced for C costs $149, or $349 with 
assembly language source, and supports Microsoft C, QuickC, 
Borland and Turbo C and C++, and all memory models. For an 
additional $50, you can obtain Designer QuickWindows, 
which allows a programmer to design windows, dialog 
boxes, and help windows interactively. A separate version of 
both products is available for Microsoft QuickBASIC and PDS 
7.x programmers. For more information, contact Software In¬ 
terphase, 82 Cucumber Hill Road, Suite 140, Foster, RI 
02825, (800) 542-2742; FAX (401) 397-6814. 


TV Toolkit Adds C++ Support 

The Turbo Vision Development Toolkit is a set of utilities 
and an object class library designed especially for use with 
Borland's Turbo Vision. The toolkit includes a resource editor 
for interactively creating or changing dialog boxes and other 
resources, a utility to convert Turbo Vision resources into 
Windows resource compiler files, and object and class 
libraries that extend Turbo Vision’s capabilities. 


Turbo Vision Development Toolkit v2.0 costs $169 and 
comes with a reference manual, tutorial, and source code for 
all objects and utilities in the package. The software is royal¬ 
ty-free and includes a 60-day, money-back guarantee. For 
more information, contact Blaise Computing Inc., 819 
Bancroft Way, Berkeley CA 94710, (510) 540-5441; 

FAX (510) 540-1938. 


ImageMan/VB Eases Visual Basic Image Manipulation 


ImageMan/VB is a new visual Basic custom control from 
Data Techniques. Programmers can use ImageMan/VB to dis¬ 
play TIFF, PCX, GIF, BMP, WMF, and EPSF images by simply set¬ 
ting a property in the custom control. The control also 
supports panning, zooming, and scaling of the displayed 
image. In addition to programmatic panning, the user can 
scroll the image using the built-in scrollbars. The control can 
print images at any location and size on a page at the resolu¬ 
tion of the printer. 


ImageMan/VB can automatically recognize graphics File 
formats, so that when DataTechniques updates the custom 
control to handle new image formats, your application can 
also handle the new formats by simply installing the new 
DLL. ImageMan/VB fully supports each file format, including 
all compression types and color formats (even 24-bit color). 

ImageMan/VB costs $249 and is royalty-free. For more in¬ 
formation, contact Data Techniques, Inc., 1000 Business 
Center Drive, Suite 120, Savannah, CA 31405, (800) 868- 
8003 or (912) 651-8003; FAX (912) 651-8021. 
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WATCOM Ships V9.0 

WATCOM is now shipping WATCOM C9.0/386, the latest 
version of their 32-bit C compiler. This compiler provides 32- 
bit code development for Windows and for DOS, using the in¬ 
cluded DOS/4GW, a 32-bit DOS extender developed by 
Rational Systems. The compiler now supports 32-bit pro¬ 
gram development for OS/2 2.0, new 486 optimizations, in¬ 
creased debugger capacity, and more Microsoft 
compatibility. 


The tools are integrated with OS/2 2.0’s WorkFrame/2 
programming environment to allow development and 
debugging of 32-bit OS/2, DOS, and Windows applications, to¬ 
tally within the OS/2 environment The package also includes 
remote debugging support under OS/2. 

WATCOM C9.0/386 costs $895. For more information, con¬ 
tact WATCOM, 415 Phillip Street, Waterloo, Ontario, 
Canada, N2L 3X2, (800) 26 5-4555; FAX (519) 747-4971. 


Whitewater Introduces ObjectGraphicsfor C++ 


Whitewater is shipping ObjectGraphics for C++, a high- 
level, object-oriented graphics library for Borland C++ and 
Turbo C++ for Windows programmers. ObjectGraphics for C++ 
extends these products to allow platform-independent sup¬ 
port for graphics, including diverse shapes, bitmaps, icons, 
multiple fonts, and text styles in Windows applications. 

ObjectGraphics for C++ provides an object-oriented alter¬ 
native to the raw Windows graphics API. You can create and 
render tool objects such as ■Pens,” "Brushes," and “Textpens" 


to control the appearance of graphic images. You can also 
specify drawing attributes such as line styles, fill patterns, 
colors, fonts, drawing combinations, and more. 

ObjectGraphics for C++ costs $195, or $390 with source 
code. It requires Borland C++ with Application Frameworks or 
Turbo C++ for Windows, 2Mb of memory, and Windows 3.x. 
For more information, contact The Whitewater Croup, 1800 
Ridge Avenue, Evanston, IL 60201, (708) 328-3800; FAX 
(708) 328-9386. 


AdamSoft Offers C/Smalltalk Windows Tools 


AdamSoft is shipping WindowsCreator, which allows 
Windows developers to interactively design user inter¬ 
faces without writing code. The company offers one ver¬ 
sion of WindowsCreator for C programmers and another 
version for users of Digitalk's Smalltalk/Windows, versions 
1.0 and 1.1. You can create color brushes interactively and 
assign colors and brushes to any Windows object. You can 
interactively assign bitmaps to menus and change them at 
runtime to create animation in menus. After designing 
your user interface, WindowsCreator automatically 
generates the code to implement the interface. For the C 
version, the generated code is separate from the applica¬ 
tion code so that you can make changes in the program 
code and still change the user interface. 


SBase provides an intelligent database interface for 
Digitalk’s Smalltalk/Windows, versions 1.0 and 1.1. With 
SBase, you can create a database interactively, defining in¬ 
dexes, files, and relations. The system handles opening and 
closing files implicitly, so you can have as many files active 
as you want The B-tree index included is written entirely in 
Smalltalk. 

WindowsCreator for Smalltalk costs $250; Windows¬ 
Creator for C costs $295; SBase costs $250. Shipping costs $10 
in Europe and $20 elsewhere, and the company accepts 
Visa. For more information, contact AdamSoft, 66 rue de 
Bourgogne, L-1272 Luxembourg, FAX +352-494768. 


GUI Computer Releases Windows Table for C++ 


ObjectTable C++ is a Windows library that implements a 
programmable multicolumn table object. The table supports 
automatic data validation for date, time, currency, and scien¬ 
tific notation data formats, clipboard cut and paste, more 
than 32Kb of data, and both horizontal and vertical scrolling. 

To add a table object to your application, you define the 
table attributes (size, number, and widths of columns, 


column titles, validations, and so on) and then provide code 
to load data into the table or save it as needed. ObjectTable 
C++ does all its own memory and event management. 

ObjectTable C++ costs $99, or $299 with source code, and 
is royalty-free. For more information, contact GUI Computer, 
Inc., P.O. Box 795908, Dallas, TX 75379, (214) 250-3472; 
FAX (214) 250-1355; BBS (214) 250-2077. 


IDC Ships TCXL V6.0 

TCXL is an interface toolkit that is part of IDC’s TesSeRact 
Development Tools. TCXL offers a graphical mouse in text 
modes, an event-driven architecture combined with virtual 
windows, virtual memory (the package supports EMS, XMS, 
VCPI, and DPMI), dialog controls, and mouse support The 
package contains more than 500 functions. This version in¬ 
cludes a CUA-style interface, the ability to build Windows ap¬ 
plications, a C++ front end, and more. 


TCXL supports C and C++ compilers from Borland, 
Microsoft, TopSpeed, Zortech, Watcom, Intel, and MetaWare. 
TCXL is available for DOS, 286 protected mode, 386 protected 
mode, Windows, OS/2, Presentation Manager, and various 
flavors of UNIX. TCXL-DOS costs $99. For more information, 
contact Innovative Data Concepts, Inc., 122 North York 
Road, Suite 5, Hatboro, PA 19040, (215) 443-9705 or (800) 
926-4551; FAX (215) 443-9753. 
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Readers' Forum 


You can now send letters to the 
editor via Internet at the following 
address: 

wdletter@rdpub.com or 
"...luunetlrdpublwdletter” 
from CompuServe: 

>INTERNET:wdletter@rdpub.com 


We ask that letters with code listings 
be submitted in an ASCII text file on an 
MS-DOS formatted disk or via email. 
Providing us an electronic copy of the 
code will prevent typographical errors 
that might result from optical scanning 
or re-keyboarding. 


Dear Mr. Burk: 

In April’s Windows/DOS Developer's 
journal you asked for suggestions for 
the "smallest, fastest” function to move 
a null-terminated Pchar to a regular 
Pascal string. How about: 

function Pchar2str(_p$tr :String) 
:string; assembler; 
asm 


push 

ds 

{ 

Turbo Pascal 




requires that DS 
be saved } 

cl d 


{ 

you can't depend 
on this flag's 
constancy ) 

les 

di, pstr 


mov 

cx,255 

{ 

string length > 255 
would be an error ) 

xor 

al ,al 



repnz 

scasb 

{ 

count how many 




bytes there are 
till \0 } 

not 

cl 



dec 

cl 

{ 

the trailing \0 
byte won't get 
moved } 

les 

di,@Result 

mov 

al ,cl 

{ 

first byte of 
result 

string := size } 

stosb 




Ids 

si,_pstr 



rep movsb { actually move 
the bytes } 

pop ds 
end; 

The general idea - using ’repnz scasb' 
to get the size into the CX register and 
then doing a ’rep movsb’ - is used by 
Zortech and Borland in their implemen¬ 
tations of the C _strcpy function, and is 
(if you count clock cycles) generally bet¬ 
ter than the obvious: 

a:lodsb 
or 
jz 

stosb 
jmp 
b:... 

There is a theoretically faster way to do 
a _strcpy, illustrated by: 


a:rept 12 { This is a TASM 
directive, not 
in TP ) 


lodsw 


or 

al ,al 

jz 

stosw 

b 

or 

ah,ah 

jz 

c 

endm 



jmp a 

b:stosb 
c:... 

However, this idea requires more space 
for the code. Page 305 of Borland’s 
Turbo Pascal™ Version 6.0 Programmer's 
Guide illustrates an inline assembler 
string function. 

Very truly yours and with thanks for 
the lovely T shirt, 

Peter Gulutzan, President 
Ocelot Computer Services Inc. 
Suite 1104 Royal Trust Tower 
Edmonton Centre 
Edmonton, AB, Canada T5J 2Z2 


al.al 

b 

a 


Thanks, Peter. I knew someone out 
there could produce this function in 
nothing flat. The lovely (well, if you're 
not allergic to purple and yellow) T- 
shirt Peter refers to is the rare, limited- 
edition, one-size-fits-all, Windows/DOS 
Developer’s Journal T-shirt we were 
giving out at Software Development 
'92. Wear it in good health and wash it 
only with like colors! —rib 


Dear Editor, 

Thank you for the excellent article 
"Fast Times with the PC Clock” by Char¬ 
les B. Allison in the April issue. 

I would like to point out that there 
is a race condition which does lead to 
erroneous results. This race occurs be¬ 
cause it is not possible to sample the 
count and the Interupt Request Register 
at the same time. 

If the timer count is sampled first 
and then the IRR, when a roll-over oc¬ 
curs between samples, an incorrect ad¬ 
justment of the clock based on the IRR 
after the count sample will be made. 

Likewise if the IRR is sampled first 
and then the timer count, when a roll¬ 
over occurs between samples, the clock 
will not be adjusted when it should be. 

The solution to this race condition is 
to sample the IRR before and after the 
counter sample. There are four possible 
states: 

State: 00 

Condition: No interrupt request before 
and after: no roll-over. 

State: 01 

Condition: Interrupt request after but 
not before: the roll-over occurred during 
the sampling. 
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Code Correction 

Alex Leavens, “Building Free-Standing Control Buttons," 3:2 (February 1992): 
Listing 2, p. 55. 

WndClass.hCursor * LoadCursor (hlnst,IDC_ARR0W); 


State: 10 

Condition: Interrupt request before but 
not after: an error condition assuming 
interrupts disabled = System Error. 

State: 11 

Condition: Interrupt request before and 
after: the roll-over occurred just before 
disabling interrupts; otherwise, it would 
have been serviced as the clock inter¬ 
rupt has a high priority. 

Now the adjustment to account for 
roll-overs can be made as follows: 

State: 00 

Condition: No adjustment required. 

State: 01 

Condition: Roll-over could occur before 
or after count sample. Assuming that 
the sampling program takes only a few 
microseconds, with the guarantee of no 
interupts as interrupts are disabled, the 
adjustment to the clock is made only if 
the count is near the beginning. Assum¬ 
ing the count sample is complemented 
so that it appears to count up, the ad¬ 
justment to the clock is made only if 
the complemented count sample is less 
than 80 hex or 8000 hex, if 16 bits of 
the counter are used. 


State: 10 

Condition: Return an error flag to the 
calling process. 

State: 11 

Condition: Adjustment required, but to 
simplify the code, this case can be 
treated the same as state 01 above. 

Very truly yours, 

John N. Ackley 
Box 10245 
St. Thomas, VI 00801 

Charles Allison responds: 

Murphy strikes again. I would like 
to thank the folks who noticed and 
contacted me about a conceptual bug 
in my “Fast Times with the PC Clock" 
article of April. There indeed is a small 
bug in the published code that can 
cause an occasional error of about 55 
milliseconds in the time read. During 
final cleanup of the original code I 
goofed and inadvertently removed the 
code fragment that prevented the 
problem. 

The bug is in the get_timr() routine. 
It can occur when tmpl = 255. The 
8253 timer's most significant byte will 
stay at 0 for many microseconds while 
the timer’s least significant byte decre¬ 
ments from 255 to 0. The interrupt re¬ 
quest will trigger when the full 16-bit 


counter decrements down. If the 
timer's most significant byte is read 
prior to the counter rolling over, i.e., 
tmpl is still 255, and the interrupt 
pending register is read shortly after 
the interrupt request event, then the 
captured time will be off by 55 mil¬ 
liseconds, a PC clock tick. 

My original solution was to test for 
pending interrupts during most, but 
not all, of the time slice. An ’if state¬ 
ment comparing tmpl to a constant 
value was used to lock out the check 
for a pending interrupt during the time 
when the race condition could occur. 
Note that tmpl counts up because the 
8253 timer chip counts down. Over 
the time slice tmpl will count from 0 
up to 255. It will remain there until 
after the interrupt request occurs and 
then it will roll over to 0. 

The value 250 was chosen to be at 
a point in time where any cpu should 
be able to complete the reading of the 
pending interrupts before the counter 
could count down and generate an in¬ 
terrupt. It was also chosen to occur 
well after the last rollover's interrupt re¬ 
quest should have been handled. The 
value 250 corresponds to a point in 
time of about 1 millisecond before the 
next interrupt and 54 milliseconds after 
the last. As long as this number meets 
both criteria, its exact value is not criti¬ 
cal. Below is the corrected getjmr 
routine. Lines that have been changed 
are marked with 1***1. 

/* get 8 bit timer contents */ 
int get_tmr(void) 

{ 

int tmpl; 
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Basie > C?! 


Basic is better than C when you 
use the ProBas library! Over 900 
routines, most in assembly, let you 
write fast, tight code without 
"C-headaches"! Easy to use, 30 
day money-back guarantee. For 
your FREE 20 page booklet call: 

800-447-9120 ext 110 
TeraTech 

Dept W6, 3 Choke Cherry Rd, 
Ste 360, Rockville MD 20850 
(301)330-6764 Fax: 963-0436 
BBS: 963-7478 9600-N-8-1 
"A Supercharger for Basic" - BYTE 

New Visual Basic tools available! 

□ Request 101 on Reader Service Card □ 



ButtonTool/EditTool Combo 
for 

Visual Basic™ Users 

ButtonTool creates "VISUAL" 
buttons and more! EditTool 
creates formatted input fields. 
$89.95 + $7 S&H. No royalties 
Visa/MC/Amex 


To order call: 
1-800-845-0386 
FAX: 713-523-0386 



OUTRIDER SYSTEMS, INC. 
3701 Kirby Dr., Ste 11 96 
Houston ,TX 77098 Dept W 


□ Request 145 on Reader Service Card □ 
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Serial Port 

Communications Tool 

SERIAL is a DOS program which turns your PC into a 
sophisticated tool for monitoring and analyzing 
asynchronous serial interface links. SERIAL captures 
both data and control line changes with time resolved to 
under 1 millisecond. Uses standard COMM hardware. 

□ Passively monitors both sides of link 

□ Easy to use window and menu controls 

□ Context sensitive help system 
O Multiple start up configurations 

O ASCII, Hex, EBCDIC, Custom Fonts — EGA/VGA 

□ Built-in font editor for custom fonts 

□ Multiple display window options 
O Triggers with audible alert 

□ Assisted baud rate determination 

□ Buffer string searches 

□ Support for FIFO buffers on 16550 UARTS 

□ Time stamping of both data and control lines 

□ CRC calculations 

□ Extensive technical manual 

□ Single user and corporate wide licenses 

□ Technical support 

Only $239 for single user license with 5 ft. cable, 
or $189 without cable. 

Allison Technical Services 

8343 Carvel, Houston, TX 77036 

PH # (713) 777-0401; FAX/BBS (713) 777-4746 

□ Request 113 on Reader Service Card □ 


WindowsCreator 

revolution !!! 


• create WINDOWS interactively 

• no need to write any code 

• You PAINT the application, not write!!! 

• object-oriented programming using 
standard C language 

• Generated C-code or Smalltalk code 
in seconds!! 

• Dialog, window, menu, cursor. 

icon, color, brush and attrib. 

editors incl. 

• interactive functionality linking 

• application code is separated from 
interface code. Few code lines connect 
application to WINDOWS interface 


AdamSoft, 66 rue de Bourgogne 
L'1272 Luxembourg 
Fax:+352-494768 VISA accepted 
Until April 30th — $200, after $299 

p&p Europe $10, elsewhere $20 


□ Request 107 on Reader Service Card □ 





Visual Basic, 
BASIC, and PDS 
programmers! 

•<tiera1 Purpose Toolboxes 
! ftojfc 
Screen Design 
(onrunicctio^s 




Loser Printing 
Scientific Applications 
isjfSlt's ond more! 


Crescent Software offers many tools for 
QuickBASIC, PDS, and Visual Basic. All 
products include complete source code, 
bee technical support, and royalties ore 
never required! K»unwi«MHfKi«waws 

CALL TOLL FREE 



1 800 35 BASIC 



CRESCENT SOFTWARE, INC. 

11 BAILEY AVENUE 
RIDGEFIELD. CT 06877-4505 
2034385300 FAX 203 431 4626 


FIX 80386 



SAVES YOUR PC 


The FIX-80386 solves the Errata 21 timing problem 
that is showing up on many PC’s. IF your PC locks up 
when running UNIX or AUTOCAD, HP BASIC, MICRO 
CADAM PLUS or memory extenders in MS-DOS you 
will need this part. The part is placed between the 80386 
and its socket. Constructed of gold pins and sockets for 
highest quality. Available immediately. ALSO ASK 
ABOUT OUR UNIQUE SOLUTIONS FOR PROBING 
PGA’s, PLCCs and LCC’s. 

IRONWOOD ELECTRONICS <— 

P.O. BOX 21 1 51, ST. PAUL. MN 55121 7 lj 

(612)431-7025; FAX (612) 432-8616 -» 


□ Request 276 on Reader Service Card □ 



RCS ,U 4.2 PVCS'“ 


TUB “ is FASTEST! 


0:19 
TUB™ 3.0 


0:09 

TUB™ 5.0 


Times are to update a 45K library on a PC/XT. PVCS and TLIB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 


TLIB™ is BEST! 

“Do not be fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare” 
John Rex, Computer Language 
"TLIB is a great system" J. Vallino, PC Tech J 

• Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus'" MAKE & Slick " MAKE 

MS-DOS $139, OS/2 $195 + shipping visa/MC 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919)233-8128 


□ Request 137 on Reader Service Card □ 
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Disassemble MS-Windows 
Executables with eee 

• Creates detailed assembly code listings 
from MS-Windows 3 jc executable files. 

• Identifies program segmentation, 
automatically! 

• Labels Window's API calls and exported 
functions, automatically! 

• Fast forward to references to specific 
Win API calls or module entry points. 

• Extracts just the function you need using 
a disassembly range. 

• Provides batch interface to define 
descriptive names and type information 
using a response file. 

• Supports 8086 - 80386. 

• Requires MS-DOS 3.x or newer. 


Man./Disk $74*5 +^Hg^2US^| 5/ nf/; 
30-Day Money^Bacll Guarantee 



Eclectic Software 

937 Jungfrau Court 
Milpitas, CA 95035 USA 


□ Request 124 on Reader Service Card □ 



Write bar Barcode Products 


Wilsoft carries a complete line of bar 
code software and hardware for your 
every need. All major bar code types 
supported. Call the most experienced 
company in the bar code field today. 
DOS and Xenix/Unix support. Por¬ 
table readers too! 

VISA/MC/AMEX/DISCOVER 

PO Box 6186 

Ft. Lauderdale, FL 33310-6186 
(305) 779-2720 
(305) 763-3096 Fax 
(800) 779-2720 Sales 

□ Request 142 on Reader Service Card □ 


Cica Windows CDROM $24.95 

Hundreds of Microsoft Windows programs 
on your desk! Utilities, games, fonts, 
icons, bitmaps, source code, programming 
tools, video/printer drivers, etc. 


Simtel-20 MSDOS CD $24.95 

420 Megs, 6000+ files at your fingertips! 
Programming tools, utilities, tech doc, 
comm, bbs, publishing, shells, editors, 
source code, etc. Thoroughly indexed. 


Walnut Creek CDROM 

1547 Palos Verdes Mall 


Suite 260 

Walnut Creek, CA 94596 

+1 800 786-9907 

+1510 947-5996 
+1510 947-1644 FAX 

ViiwMC 
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Opt-Tech Sort/Merge 


Extremely fast Sort / Merge / 
Select utility. Run as an MS- 
DOS command or CALL as a 
subroutine. 

Supports most languages and 
filetypes including Btrieve and 
dBase. Unlimited filesizes, mul¬ 
tiple keys and much more! 

MS-DOS, Windows $149. 
OS/2, UNIX $249. 


Opt-Tech Data Processing 

P. O. Box 678 
Zephyr Cove. NV 89448 

(702) 588-3737 


□ Request 127 on Reader Service Card □ 
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/* WARNING should be called with 
interrupts disabled or risk 
glitching the who is who sequence 
of bytes for upper lower byte 


outp(TIMERC.O); /* latch data */ 
inp(TIMERO); /* throw away lsb */ 
if( (tmpl = 255 - 

(Oxff & inp(TIMERO)) )< 250 ) /***/ 
{ 1***1 
outp(PIC00,0CW3IR); 

/* request pending 
interrupt status */ 

tmpl |= 

( inp(PICOO) & 0x01) ? 0x100 : 0x00; 

/* get the pending status 
for timer int irqOl*/ 

/* set - timer int 
not done yet *1 

) 1***1 


return tmpl; 

/* use PIC for rollover 
not captured yet */ 

} /* end of get timer contents */ 


Mr. Burk, 

I recently received the April issue of 
Windows/DOS and I just wanted to drop 
a note letting you know I enjoyed this 
issue more than usual. 

The article on the FaxBios specifica¬ 
tions was clear, concise and well-written. 
It was enjoyable to read. After reading 
the article, I believe I actually could write 
a program that would communicate with 
a FaxBios-compatible fax card. Now if only 
my fax 3rd would arrive... 

Continuing on the same vein as the 
FaxBios article, I would love to see an 


article on how to program QIC-standard 
floppy-based tape drives like the Ar- 
chive-XL line from Maynard. Or those 
from Colorado Memory Systems. 

Cordially, 

Richard L. Rosenheim 
5712 North Casa Blan3 Rd. 

Paradise Valley, AZ 85253 

Victor Volkman does a fabulous job 
of studying specifications and 
products and distilling out the most 
important technical aspects for us. His 
next article covers the Advanced 
Power Management specification, 
from Intel and Microsoft. Thanks for 
the feedback and the article sugges¬ 
tions. -rib 
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EGAD 

Screen Print Package 

• Supports VGA, EGA, CGA, 
MGA displays up to 800x600 

• Select printout colors/gray 
tones; print any rectangular 
region; enlarge graphics 1-4 
times; many other features 

• Works with most printers 

• TSR (Shift-PrtSc) or call from 
your program. TSR is 9-15K. 

• Licensing available. 

$35.00 postpaid. Free catalog. 


LS Software 8139 E. Mawson, 
Mesa, AZ 85207 (602) 380-9175 

□ Request 119 on Reader Service Card □ 
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COM1: - COM4: 
WITH WINDOWS! 

• 1.2, OR 4 PORT RS-232 BOARDS 

• RS-232 AND RS-422 VERSIONS 
. WtNOOWS UTIUTY SOFTWARE 

PROVIDED 

. XT AND AT INTERRUPT JUMPERS 
. OTHER PRODUCTS INCLUDING 



□ Request 115 on Reader Service Card □ 
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BAR CODE 
SOURCE CODE 

$ 45.00 

Source code for printing UPC codes, 
postal bar codes, and most other 
popular formats. Comprehensive 
collection of programs and routines 
in C, C++, Paradox, Quick Basic, 
GW Basic, Visual Basic, & Dbase. 

No runtime royalties. 

Eastern Digital Resources 
PO Box 1451 - Clearwater, SC 29822-1451 
Tel. (803) 593-0870 Fax. (803) 593-4522 
VISA - MC - COD - POS WELCOME 


□ Request 110 on Reader Sendee Card □ 


CREATE MULTI¬ 
LINGUAL PROGRAMS 

Translator's Apprsntica Toolkit 

Access the huge international market by 
converting your C programs to externalized text 
for easy translation into other languages (Spanish, 
German, etc.). The Translator's Apprsntica is a 
complete extemalization and text management 
package. 

□ Automatically converts existing source code. 

□ Different language versions without source 
changes. 

O Create a single executable containing external 
text. 

□ Unlimited text size; Fast! access. 

□ Reduced memory requirements. 

□ Export/Import ASCII text. 

□ Multiple simultaneous languages. 

□ Translation service available. 

30-day money-back guarantee. Order now, $175 
including program, access functions, source. 

C or Dipper. 

Frontier Software Services 
31 Mystic Ave. 

Winchester, MA 01890 
[SI 7] 759-2161 _ 

□ Request 112 on Reader Service Card □ 


























WINDOWSTOOLS 
FILE MANAGEMENT 

This professional Windows utility package includes 
Multicopy, Systemlnfo, TextSearch, and TextEdit. 

Multicopy is a fast copying utility that supports the 
Windows Memory Manager and can use RAM disk and 
hard disk during the copying process. Formatting, multi¬ 
ple copying, and successive numbering are also included. 

Systemlnfo shows in a single glance how your 
computer’s resources are used In the Windows environ¬ 
ment. A graphic diagram depicts the amount of space 
occupied by your programs, data, and directories. 

TextSearch is a fast and fully functional text search 
program. TextSearch locates specific positions within 
files, directories, on hard disks, even on your network. 

TextEdit allows you to view and edit your files in 
hexadecimal or character oriented styles. TextEdit also 
includes the ability to edit several files simultaneously 
(MD1). Files can be up to 64 MB. AU for $98! MC/V 

The OXKO Corporation 

P.O. Box 6674, Annapolis, MD 21401 

Tel: (301) 266-1671 Fax: (410) 266-6572 


□ Request 346 on Reader Service Card □ 


Program WINDOWS™ 
With UNIX S Strength 

Our programmers love Windows, but can't live without 
the time proven power of Unix. With Winix's visual 
Unix tools for Windows they have it all, and you will 
agree, the sum is greater than it's parts. 

♦ Point & click your way through files with cd & Is. 

♦ Split & join portions of files using head & tail. 

♦ Search & replace text with visual grep & gres. 

Plus, the Winix environment lets you graphically link 
any sequence of operations together and direct the 
flow of information, for one shot processing, or to 
perform the routine operations you need today and in 
the future. 

Include a copy of this ad and we'll also send you our 
Windows text editor, DCedit. Indicate 3.5" or 5.25“ 
disks and send check or M.O. for just $35 + $4 S&H. 
□□ Double Click 

3833 Washburn Ave. S. - Minneapolis. MN 55410 - (612) 920-7829 

□ Request 129 on Reader Service Card □ 


Windows Edit Controls 

InControl Toolbox. Custom Windows 
edit controls for the entry of: 

□ Integers, Floating point 

□ Dates 

□ Formatted Text 

□ Regular Expression 

□ Display of date and time 

Provides hooks for programmer 
validation routines and creation of 
specialized controls. 

For demo, call BBS: (512) 335-5079 
Without source $99. With source $249. 
For info or orders call: The Connection 
800-336-1166 or (216) 494-3781 
Fax: (216) 494-5260 


MantaSoft Partners (512)335-3497 
P.O. Box 203551 
Austin, TX 78720-3551 


□ Request 114 on Reader Service Card □ 


SDLC, HDLC 
And X.25 Support 

Use Sangoma hardware and software 
to provide fast, cost effective, robust 
and easy to use SDLC, HDLC and X.25 
links from MS-DOS, UNIX, Concurrent 
DOS etc. 

All real time communication functions 
are performed by intelligent coproces¬ 
sor card. Line speeds up to 160 kbps 
are supported. Powerful debugging, 
line statistics and trace facilities are 
included. 

Full function SNA emulation packages 
also available. 

Sangoma Technologies Inc. 

w (416) 474-1990 (800) 388-2475 




□ Request 286 on Reader Service Card □ 


32-bit Protected Mode 
386 C Graphics Library 

Intel 386/486 C Code Builder 
MetaWare, MicroWay, SVS, 
Watcom & Zortech with 
Phar Lap 3861 ASM 

Mixed Raster/Vector, 
Scalable, Rotatable Font, 
VGA, SVGA, 8514/A, VESA, 
Hercules Graphics Station 
through 1024x768x256 (8-bit), 
640x480x32k (16-bit), 
512x480x16.7m (32-bit), 
WYSIWYG HP-GL/PostScript 
$200 NO ROYALTIES 
FULL SOURCE CODE 
Gary R. Olhoeft 
P.O. Box 10870 Edgemont 
Golden, CO 80401-0620 
303-877-3697 CIS 76665,2021 

□ Request 294 on Reader Service Card □ 


2 ™ 

The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 


ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 


□ Request 104 on Reader Service Card □ 
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C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, functions-vs-files index. 

• C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METR1C ($59) Counts path complexity, 
counts comments, code, 'C' statements. 

• C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

• C-DOC SPECIAL ($199) All 5 programs 
integrated as 1 DOS program. Processes 
multiple directories/files up to 15,000 lines. 

• NEW! ($299) C-DOC Professional 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deferred reports. 

• 30-DAY Money-back guarantee CALL NOW 

SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 

ONT, Canada. L5N-4M1 (416)-858-4466 


see AD INDEX for our larger ad 
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NETWORK 

CONTROL 

LIBRARIES 

NETBIOS ROUTINES allows ac¬ 
cess to low-level network func¬ 
tions. Name, session, and 
datagram routines. Wait and no¬ 
wait options. $99 

NETBIOS DLL for Windows $199 

NETWORK MASTER provides 
access to Netware internal func¬ 
tions. Complete network control 
from your compiled programs! $99 

Starlight Software 

P.O. Box 1090 

Wheeling, IL 60090 

(708) 394-0622 _ 

□ Request 170 on Reader Service Card □ 
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windows/DOS Code Listings 
Available via UUCP! 

The listings for all code in each issue of Win¬ 
dows/DOS Developer's Journal are now being archived 
in machine-readable form by UUNET Technologies, Inc 
Each archive file has a pathname of the form 

uunet!~/published/windowsdos/19YY/monYY.tar.Z 

where mon is the first three letters of the month (jan, 
feb, etc.) and YY is the last two digits of the year (e.g., 
92). To uncompress the archive file, use compress -d 
files-, then use tar xvf file to expand the archive 
into its component files. See the file called 
filename, txt, included in each archive, for an explana¬ 
tion of the archive's contents. 

You may download these archive files via uucp 
even if you do not have a UUNET account: have your 
uucp program call 1-900-GOT-SRCS and use the login 
name uucp, no password. Callers will be charged a 
nominal fee for connect time (currently 50 cents per 
minute). The modems are mostly Telebit T3000’s, 
which support most of the faster communication 
protocols. 

Code for each issue is also available on diskette from 
R&D Publications at $5.00 per disk (call 913-841-1631 for 
information). 


ST@P! 


Over 18,000 
Windows developers 
are reading this ad. 
Shouldn’t your product 
be here? 

Call us at 913-841-1631 
to receive a free media kit. 
You’ll be glad you did. 

Windows/DOS 

DEVELOPER'S JOURNAL 


CALL 

913 - 841-1631 

TODAY! 
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TheTesSeRact Programmer's Power Pak 

from INNOVATIVE DATA CONCEPTS, INC., is an all-in- 
one, dynamic, cost-effective package that combines the 
power of basic user interface development and interactive 
design with high speed data compression, customized 
printer output and data file management, all at your fingertips! 




The TCXL User Interface Development System 
One of the fastest and smallest CUA-style interface 
packages on the market.TCXL's event-driven architecture is 
combined with virtual windows (window sizes are limited by 
available RAM; video display viewports may be manipulated 
independently), virtual memory (EMS, XMS, VCPI and 
DPMI supported), dialog controls, mouse support, and 
more.TCXL contains nearly 500 multi-purpose functions, 
and is the cornerstone of the Power Pak. (TCXL is also 
available separately for DOS, Windows, OS/2 and UNIX; for 
both real and protected modes; supporting textual and 
graphical displays.) 

TheTesSeRact Screen Designer 
TSD combines all the elements of TCXL's CUA architecture 
to allow full-featured program prototyping and source code 
generation. TSD generates commented C source code with 
all interface objects described. This allows complex user 
interfaces to be designed in minutes. 

TheTesSeRact Compression System 
TCOMP gives you high-speed access to five of the most 
popular compression methods available, all based on the 
Lempel-Ziv algorithm. 




The TesSeRact Printer Control System 
TPRINT lets you design your program's output without regard 
to what printer is attached to the end-user's computer. Many 
popular drivers are included, as well as a printer configuration 
module as "stand-alone" or to link with your program. 


We've made it easier than 
ever for you to build 
applications the way you 
want, without sacrificing 
your bottom line! 


The TesSeRact File Management System 

TFILE is an indexed file access system that is fully dBase 
III/III+/IV compatible. TFILE can also maintain .DBF, .DBT, 
.NDX and .MDX files, as well as Clipper-compatible indexes. 

PLUS...Two Additional Bonuses 

The TCXL Advanced Utilities Diskette and the IDC 

Programmer's Utilities Diskette contain a host of useful 

programs, including source code to many TCXL utility 

programs, and a high speed, line- oriented stream editor 

(SED). 


TheTesSeRact Programmer's Power Pak 

A great buy at just $369, a savings of $84 over individual 
product purchases. Full documentation and source code 
provided. No run-time royalties. Site licenses available. And 
of course, free telephone technical support. Call or fax your 
order today! Toll free 800-926-4551 or +215-443-9753. 
MC/VISA/AMEX accepted. Full 30 day money-back 
guarantee! 



Free Demo Disk Available. 

"TesSeRact 

DEVELOPMENT TOOLS 


CALL OR FAX YOUR ORDER TODAY! MC/VISA/AMEX ACCEPTED 
TOLL FREE 1-800-926-4551 or 215-443-9705 FAX 215-443-9753 
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Get Inside WINDOWS! 




sof m 



MICROSOFT 

W1NDCKVS 

Vtjji JO CcmpaiNc PrruJja 


V 


Debug Windows at the systems level! 


Soft-ICE/W takes you inside Windows! Debug and explore with power 
and flexibility not found in any other Windows debugger! Soft-ICE/W 
allows you to debug at the systems or applications level or simply learn 
the inner workings of Windows. 

• Debug VxD's, drivers and interrupt routines at source level 

• Debug interactions between DOS T&SR's and Windows Apps 

• Debug programs in DOS boxes 

• Display valuable system information 

(from the total memory occupied by a Windows application, to the 
complex internal structures of Windows) 

Soft-ICE/W uses the 386/486 architecture to provide break point 
capabilities that normally require external hardware. Nu-Mega, which 
pioneered this technology with the introduction of its award winning 
Soft/ICE for DOS, now gives Windows programmers the same debug¬ 
ging power... and still at a software price. 

Own the debugger that combines the best "view" of Windows internals 
with the most powerful break points of any software debugger. 

Soft-ICE/W. . . Only s 386 

CodeView for Windows users: see what you’re debugging without flash. 
CV/1 version 2.0 runs CodeView in a graphics window while viewing your 
application screen. Runs on anv display that supports Windows. 

CV/1 . . . Only $129 

Buy any Nu-Mega product and get CV/1 for only $69. 


- WHAT THE EXPERTS ARE SAYING - 

"Soft-ICE for Windows is great! It helped me 
find, in fifteen minutes, a killer bug in a 
Windows virtual device driver that had 
eluded two people for several months. I 
can't see doing Windows development of 
any kind - whether writing Windows 
applications, device drivers, or even DOS 
programs that have to run under Windows -- 
without it. In addition to being great for 
finding bugs, Soft-ICE for Windows has been 
essential for my work on a forthcoming book: 
on Undocumented Windows . Soft-ICE for 
Windows goes anywhere and does 
everything, so it's essential for anyone who 
wants to poke around inside Windows 
Enhanced mode. DOS programmers will find 
it a perfect way to learn how the Windows 
DOS extender and DPMI server work, and 
how Windows interacts with DOS. Windows 
Enhanced mode is the hacker's paradise of 
the 90s, and Soft-ICE for Windows is the tool 
that every serious Windows or DOS hacker 
will need. Nu-Mega has done a brilliant 
job!" 

Andrew Schulman 

Software Engineer. Phar Lap Software 

Editor. Undocumented DOS 

Coauthor. Undocumented Windows (forthcoming ) 


Call (603) 889-2386 
fax (603) 889-1135 
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Mega 

RISK = NULL 

30 DAY 

MONEY-BACK GUARANTEE. 

P.O. Box 7780 

Nashua, NH 03060-7780 U.S.A. 

^TECHNOLOGIES INC 



MICROSOFT WINDOWS IS A REGISTERED TRADEMARK OF MICROSOFT CORP. Soft-ICE/W AND CV/1 ARE TRADEMARKS OF NU-MEGA TECHNOLOGIES, INC. 
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